rubysl-webrick 1.0.0 → 2.0.0

data/lib/webrick/httpauth/basicauth.rb

@@ -13,10 +13,31 @@ require 'webrick/httpauth/authenticator'
 
 module WEBrick
   module HTTPAuth
+
+    ##
+    # Basic Authentication for WEBrick
+    #
+    # Use this class to add basic authentication to a WEBrick servlet.
+    #
+    # Here is an example of how to set up a BasicAuth:
+    #
+    #   config = { :Realm => 'BasicAuth example realm' }
+    #
+    #   htpasswd = WEBrick::HTTPAuth::Htpasswd.new 'my_password_file'
+    #   htpasswd.set_passwd config[:Realm], 'username', 'password'
+    #   htpasswd.flush
+    #
+    #   config[:UserDB] = htpasswd
+    #
+    #   basic_auth = WEBrick::HTTPAuth::BasicAuth.new config
+
     class BasicAuth
       include Authenticator
 
-      AuthScheme = "Basic"
+      AuthScheme = "Basic" # :nodoc:
+
+      ##
+      # Used by UserDB to create a basic password entry
 
       def self.make_passwd(realm, user, pass)
         pass ||= ""
@@ -25,16 +46,31 @@ module WEBrick
 
       attr_reader :realm, :userdb, :logger
 
+      ##
+      # Creates a new BasicAuth instance.
+      #
+      # See WEBrick::Config::BasicAuth for default configuration entries
+      #
+      # You must supply the following configuration entries:
+      #
+      # :Realm:: The name of the realm being protected.
+      # :UserDB:: A database of usernames and passwords.
+      #           A WEBrick::HTTPAuth::Htpasswd instance should be used.
+
       def initialize(config, default=Config::BasicAuth)
         check_init(config)
         @config = default.dup.update(config)
       end
 
+      ##
+      # Authenticates a +req+ and returns a 401 Unauthorized using +res+ if
+      # the authentication was not correct.
+
       def authenticate(req, res)
         unless basic_credentials = check_scheme(req)
           challenge(req, res)
         end
-        userid, password = basic_credentials.unpack("m*")[0].split(":", 2) 
+        userid, password = basic_credentials.unpack("m*")[0].split(":", 2)
         password ||= ""
         if userid.empty?
           error("user id was not given.")
@@ -52,12 +88,19 @@ module WEBrick
         req.user = userid
       end
 
+      ##
+      # Returns a challenge response which asks for for authentication
+      # information
+
       def challenge(req, res)
         res[@response_field] = "#{@auth_scheme} realm=\"#{@realm}\""
         raise @auth_exception
       end
     end
 
+    ##
+    # Basic authentication for proxy servers.  See BasicAuth for details.
+
     class ProxyBasicAuth < BasicAuth
       include ProxyAuthenticator
     end

data/lib/webrick/httpauth/digestauth.rb

@@ -19,18 +19,70 @@ require 'digest/sha1'
 
 module WEBrick
   module HTTPAuth
+
+    ##
+    # RFC 2617 Digest Access Authentication for WEBrick
+    #
+    # Use this class to add digest authentication to a WEBrick servlet.
+    #
+    # Here is an example of how to set up DigestAuth:
+    #
+    #   config = { :Realm => 'DigestAuth example realm' }
+    #
+    #   htdigest = WEBrick::HTTPAuth::Htdigest.new 'my_password_file'
+    #   htdigest.set_passwd config[:Realm], 'username', 'password'
+    #   htdigest.flush
+    #
+    #   config[:UserDB] = htdigest
+    #
+    #   digest_auth = WEBrick::HTTPAuth::DigestAuth.new config
+    #
+    # When using this as with a servlet be sure not to create a new DigestAuth
+    # object in the servlet's #initialize.  By default WEBrick creates a new
+    # servlet instance for every request and the DigestAuth object must be
+    # used across requests.
+
     class DigestAuth
       include Authenticator
 
-      AuthScheme = "Digest"
-      OpaqueInfo = Struct.new(:time, :nonce, :nc)
-      attr_reader :algorithm, :qop
+      AuthScheme = "Digest" # :nodoc:
+
+      ##
+      # Struct containing the opaque portion of the digest authentication
+
+      OpaqueInfo = Struct.new(:time, :nonce, :nc) # :nodoc:
+
+      ##
+      # Digest authentication algorithm
+
+      attr_reader :algorithm
+
+      ##
+      # Quality of protection.  RFC 2617 defines "auth" and "auth-int"
+
+      attr_reader :qop
+
+      ##
+      # Used by UserDB to create a digest password entry
 
       def self.make_passwd(realm, user, pass)
         pass ||= ""
         Digest::MD5::hexdigest([user, realm, pass].join(":"))
       end
 
+      ##
+      # Creates a new DigestAuth instance.  Be sure to use the same DigestAuth
+      # instance for multiple requests as it saves state between requests in
+      # order to perform authentication.
+      #
+      # See WEBrick::Config::DigestAuth for default configuration entries
+      #
+      # You must supply the following configuration entries:
+      #
+      # :Realm:: The name of the realm being protected.
+      # :UserDB:: A database of usernames and passwords.
+      #           A WEBrick::HTTPAuth::Htdigest instance should be used.
+
       def initialize(config, default=Config::DigestAuth)
         check_init(config)
         @config                 = default.dup.update(config)
@@ -44,7 +96,6 @@ module WEBrick
         @nonce_expire_period    = @config[:NonceExpirePeriod]
         @nonce_expire_delta     = @config[:NonceExpireDelta]
         @internet_explorer_hack = @config[:InternetExplorerHack]
-        @opera_hack             = @config[:OperaHack]
 
         case @algorithm
         when 'MD5','MD5-sess'
@@ -52,7 +103,7 @@ module WEBrick
         when 'SHA1','SHA1-sess'  # it is a bonus feature :-)
           @h = Digest::SHA1
         else
-          msg = format('Alogrithm "%s" is not supported.', @algorithm)
+          msg = format('Algorithm "%s" is not supported.', @algorithm)
           raise ArgumentError.new(msg)
         end
 
@@ -62,6 +113,10 @@ module WEBrick
         @mutex = Mutex.new
       end
 
+      ##
+      # Authenticates a +req+ and returns a 401 Unauthorized using +res+ if
+      # the authentication was not correct.
+
       def authenticate(req, res)
         unless result = @mutex.synchronize{ _authenticate(req, res) }
           challenge(req, res)
@@ -72,6 +127,10 @@ module WEBrick
         return true
       end
 
+      ##
+      # Returns a challenge response which asks for for authentication
+      # information
+
       def challenge(req, res, stale=false)
         nonce = generate_next_nonce(req)
         if @use_opaque
@@ -96,6 +155,8 @@ module WEBrick
 
       private
 
+      # :stopdoc:
+
       MustParams = ['username','realm','nonce','uri','response']
       MustParamsAuth = ['cnonce','nc']
 
@@ -118,18 +179,17 @@ module WEBrick
         }
 
         if !check_uri(req, auth_req)
-          raise HTTPStatus::BadRequest  
+          raise HTTPStatus::BadRequest
         end
 
-        if auth_req['realm'] != @realm  
+        if auth_req['realm'] != @realm
           error('%s: realm unmatch. "%s" for "%s"',
                 auth_req['username'], auth_req['realm'], @realm)
           return false
         end
 
-        auth_req['algorithm'] ||= 'MD5' 
-        if auth_req['algorithm'] != @algorithm &&
-           (@opera_hack && auth_req['algorithm'] != @algorithm.upcase)
+        auth_req['algorithm'] ||= 'MD5'
+        if auth_req['algorithm'].upcase != @algorithm.upcase
           error('%s: algorithm unmatch. "%s" for "%s"',
                 auth_req['username'], auth_req['algorithm'], @algorithm)
           return false
@@ -165,8 +225,7 @@ module WEBrick
           nonce_is_invalid = true
         end
 
-        if /-sess$/ =~ auth_req['algorithm'] ||
-           (@opera_hack && /-SESS$/ =~ auth_req['algorithm'])
+        if /-sess$/i =~ auth_req['algorithm']
           ha1 = hexdigest(password, auth_req['nonce'], auth_req['cnonce'])
         else
           ha1 = password
@@ -222,15 +281,15 @@ module WEBrick
             end
           }.join(', ')
         end
-        info('%s: authentication scceeded.', auth_req['username'])
+        info('%s: authentication succeeded.', auth_req['username'])
         req.user = auth_req['username']
         return true
       end
 
       def split_param_value(string)
         ret = {}
-        while string.size != 0
-          case string           
+        while string.bytesize != 0
+          case string
           when /^\s*([\w\-\.\*\%\!]+)=\s*\"((\\.|[^\"])*)\"\s*,?/
             key = $1
             matched = $2
@@ -320,7 +379,7 @@ module WEBrick
         uri = auth_req['uri']
         if uri != req.request_uri.to_s && uri != req.unparsed_uri &&
            (@internet_explorer_hack && uri != req.path)
-          error('%s: uri unmatch. "%s" for "%s"', auth_req['username'], 
+          error('%s: uri unmatch. "%s" for "%s"', auth_req['username'],
                 auth_req['uri'], req.request_uri.to_s)
           return false
         end
@@ -330,12 +389,18 @@ module WEBrick
       def hexdigest(*args)
         @h.hexdigest(args.join(":"))
       end
+
+      # :startdoc:
     end
 
+    ##
+    # Digest authentication for proxy servers.  See DigestAuth for details.
+
     class ProxyDigestAuth < DigestAuth
       include ProxyAuthenticator
 
-      def check_uri(req, auth_req)
+      private
+      def check_uri(req, auth_req) # :nodoc:
         return true
       end
     end

data/lib/webrick/httpauth/htdigest.rb

@@ -13,9 +13,26 @@ require 'tempfile'
 
 module WEBrick
   module HTTPAuth
+
+    ##
+    # Htdigest accesses apache-compatible digest password files.  Passwords are
+    # matched to a realm where they are valid.  For security, the path for a
+    # digest password database should be stored outside of the paths available
+    # to the HTTP server.
+    #
+    # Htdigest is intended for use with WEBrick::HTTPAuth::DigestAuth and
+    # stores passwords using cryptographic hashes.
+    #
+    #   htpasswd = WEBrick::HTTPAuth::Htdigest.new 'my_password_file'
+    #   htpasswd.set_passwd 'my realm', 'username', 'password'
+    #   htpasswd.flush
+
     class Htdigest
       include UserDB
 
+      ##
+      # Open a digest password database at +path+
+
       def initialize(path)
         @path = path
         @mtime = Time.at(0)
@@ -26,6 +43,9 @@ module WEBrick
         reload
       end
 
+      ##
+      # Reloads passwords from the database
+
       def reload
         mtime = File::mtime(@path)
         if mtime > @mtime
@@ -44,6 +64,10 @@ module WEBrick
         end
       end
 
+      ##
+      # Flush the password database.  If +output+ is given the database will
+      # be written there instead of to the original path.
+
       def flush(output=nil)
         output ||= @path
         tmp = Tempfile.new("htpasswd", File::dirname(output))
@@ -56,6 +80,10 @@ module WEBrick
         end
       end
 
+      ##
+      # Retrieves a password from the database for +user+ in +realm+.  If
+      # +reload_db+ is true the database will be reloaded first.
+
       def get_passwd(realm, user, reload_db)
         reload() if reload_db
         if hash = @digest[realm]
@@ -63,6 +91,9 @@ module WEBrick
         end
       end
 
+      ##
+      # Sets a password in the database for +user+ in +realm+ to +pass+.
+
       def set_passwd(realm, user, pass)
         @mutex.synchronize{
           unless @digest[realm]
@@ -72,13 +103,19 @@ module WEBrick
         }
       end
 
+      ##
+      # Removes a password from the database for +user+ in +realm+.
+
       def delete_passwd(realm, user)
         if hash = @digest[realm]
           hash.delete(user)
         end
       end
 
-      def each
+      ##
+      # Iterate passwords in the database.
+
+      def each # :yields: [user, realm, password_hash]
         @digest.keys.sort.each{|realm|
           hash = @digest[realm]
           hash.keys.sort.each{|user|

data/lib/webrick/httpauth/htgroup.rb

@@ -11,7 +11,26 @@ require 'tempfile'
 
 module WEBrick
   module HTTPAuth
+
+    ##
+    # Htgroup accesses apache-compatible group files.  Htgroup can be used to
+    # provide group-based authentication for users.  Currently Htgroup is not
+    # directly integrated with any authenticators in WEBrick.  For security,
+    # the path for a digest password database should be stored outside of the
+    # paths available to the HTTP server.
+    #
+    # Example:
+    #
+    #   htgroup = WEBrick::HTTPAuth::Htgroup.new 'my_group_file'
+    #   htgroup.add 'superheroes', %w[spiderman batman]
+    #
+    #   htgroup.members('superheroes').include? 'magneto' # => false
+
     class Htgroup
+
+      ##
+      # Open a group database at +path+
+
       def initialize(path)
         @path = path
         @mtime = Time.at(0)
@@ -20,6 +39,9 @@ module WEBrick
         reload
       end
 
+      ##
+      # Reload groups from the database
+
       def reload
         if (mtime = File::mtime(@path)) > @mtime
           @group.clear
@@ -34,6 +56,10 @@ module WEBrick
         end
       end
 
+      ##
+      # Flush the group database.  If +output+ is given the database will be
+      # written there instead of to the original path.
+
       def flush(output=nil)
         output ||= @path
         tmp = Tempfile.new("htgroup", File::dirname(output))
@@ -48,11 +74,17 @@ module WEBrick
         end
       end
 
+      ##
+      # Retrieve the list of members from +group+
+
       def members(group)
         reload
         @group[group] || []
       end
 
+      ##
+      # Add an Array of +members+ to +group+
+
       def add(group, members)
         @group[group] = members(group) | members
       end

data/lib/webrick/httpauth/htpasswd.rb

@@ -13,9 +13,27 @@ require 'tempfile'
 
 module WEBrick
   module HTTPAuth
+
+    ##
+    # Htpasswd accesses apache-compatible password files.  Passwords are
+    # matched to a realm where they are valid.  For security, the path for a
+    # password database should be stored outside of the paths available to the
+    # HTTP server.
+    #
+    # Htpasswd is intended for use with WEBrick::HTTPAuth::BasicAuth.
+    #
+    # To create an Htpasswd database with a single user:
+    #
+    #   htpasswd = WEBrick::HTTPAuth::Htpasswd.new 'my_password_file'
+    #   htpasswd.set_passwd 'my realm', 'username', 'password'
+    #   htpasswd.flush
+
     class Htpasswd
       include UserDB
 
+      ##
+      # Open a password database at +path+
+
       def initialize(path)
         @path = path
         @mtime = Time.at(0)
@@ -25,6 +43,9 @@ module WEBrick
         reload
       end
 
+      ##
+      # Reload passwords from the database
+
       def reload
         mtime = File::mtime(@path)
         if mtime > @mtime
@@ -35,7 +56,7 @@ module WEBrick
               case line
               when %r!\A[^:]+:[a-zA-Z0-9./]{13}\z!
                 user, pass = line.split(":")
-              when /:\$/, /:\{SHA\}/
+              when /:\$/, /:{SHA}/
                 raise NotImplementedError,
                       'MD5, SHA1 .htpasswd file not supported'
               else
@@ -48,6 +69,10 @@ module WEBrick
         end
       end
 
+      ##
+      # Flush the password database.  If +output+ is given the database will
+      # be written there instead of to the original path.
+
       def flush(output=nil)
         output ||= @path
         tmp = Tempfile.new("htpasswd", File::dirname(output))
@@ -60,20 +85,33 @@ module WEBrick
         end
       end
 
+      ##
+      # Retrieves a password from the database for +user+ in +realm+.  If
+      # +reload_db+ is true the database will be reloaded first.
+
       def get_passwd(realm, user, reload_db)
         reload() if reload_db
         @passwd[user]
       end
 
+      ##
+      # Sets a password in the database for +user+ in +realm+ to +pass+.
+
       def set_passwd(realm, user, pass)
         @passwd[user] = make_passwd(realm, user, pass)
       end
 
+      ##
+      # Removes a password from the database for +user+ in +realm+.
+
       def delete_passwd(realm, user)
         @passwd.delete(user)
       end
 
-      def each
+      ##
+      # Iterate passwords in the database.
+
+      def each # :yields: [user, password]
         @passwd.keys.sort.each{|user|
           yield([user, @passwd[user]])
         }