htauth 1.2.0 → 2.0.0

data/lib/htauth/md5.rb

@@ -2,8 +2,7 @@ require 'htauth/algorithm'
 require 'digest/md5'
 
 module HTAuth
-
-  # an implementation of the MD5 based encoding algorithm 
+  # Internal: an implementation of the MD5 based encoding algorithm
   # as used in the apache htpasswd -m option
   class Md5 < Algorithm
 

data/lib/htauth/passwd_entry.rb

@@ -1,18 +1,24 @@
-require 'htauth/errors'
+require 'htauth/error'
 require 'htauth/entry'
 require 'htauth/algorithm'
 
 module HTAuth
-  class InvalidPasswdEntry < StandardError ; end
-
-  # A single record in an htdigest file.  
+  # Internal: Object version of a single entry from a htpasswd file
   class PasswdEntry < Entry
 
+    # Internal: the user of this entry
     attr_accessor :user
+    # Internal: the password digest of this entry
     attr_accessor :digest
+    # Internal: the algorithm used to create the digest of this entry
     attr_reader   :algorithm
 
     class << self
+      # Internal: Create an instance of this class from a line of text
+      #
+      # line - a line of text from a htpasswd file
+      #
+      # Returns an instance of PasswdEntry
       def from_line(line)
         parts = is_entry!(line)
         d = PasswdEntry.new(parts[0])
@@ -21,17 +27,26 @@ module HTAuth
         return d
       end
 
-      # test if a line is an entry, raise InvalidPasswdEntry if it is not.
-      # an entry must be composed of 2 parts, username:encrypted_password
-      # where username, and password do not contain the ':' character 
+      # Internal: test if the given line is valid for this Entry class
+      #
+      # A valid entry is a single line composed of two parts; a username and a
+      # password separated by a ':' character. Neither the username nor the
+      # password may contain a ':' character
+      #
+      # line - a line of text from a file
+      #
+      # Returns the individual parts of the line
+      # Raises InvalidPasswdEntry if it is not an valid entry
       def is_entry!(line)
         raise InvalidPasswdEntry, "line commented out" if line =~ /\A#/
         parts = line.strip.split(":")
-        raise InvalidPasswdEntry, "line must be of the format username:pssword" if parts.size != 2
+        raise InvalidPasswdEntry, "line must be of the format username:password" if parts.size != 2
         return parts
       end
 
-      # test if a line is an entry and return true or false
+      # Internal: Returns whether or not the line is a valid entry
+      #
+      # Returns true or false
       def is_entry?(line)
         begin
           is_entry!(line)
@@ -42,13 +57,15 @@ module HTAuth
       end
     end
 
+    # Internal: Create a new Entry with the given user, password, and algorithm
     def initialize(user, password = nil, alg = Algorithm::DEFAULT, alg_params = {} )
       @user      = user
       alg = Algorithm::DEFAULT if alg == Algorithm::EXISTING 
       @algorithm = Algorithm.algorithm_from_name(alg, alg_params)
-      @digest    = algorithm.encode(password) if password
+      @digest    = calc_digest(password)
     end
 
+    # Internal: set the algorithm for the entry
     def algorithm=(alg)
       if alg.kind_of?(Array) then
         if alg.size == 1 then
@@ -62,35 +79,50 @@ module HTAuth
       return @algorithm
     end
 
+    # Internal: Update the password of the entry with its new value
+    #
+    # If we have an array of algorithms, then we set it to CRYPT
     def password=(new_password)
       if algorithm.kind_of?(Array) then
-        @algorithm = Algorithm.algorithm_from_name("crypt")
+        @algorithm = Algorithm.algorithm_from_name(Algorithm::CRYPT)
       end
-      @digest = algorithm.encode(new_password)
+      @digest = calc_digest(new_password)
+    end
+
+    # Internal: calculate the new digest of the given password
+    def calc_digest(password)
+      return nil unless password
+      algorithm.encode(password)
     end
 
+    # Public: Check if the given password is the password of this entry
     # check the password and make sure it works, in the case that the algorithm is unknown it
     # tries all of the ones that it thinks it could be, and marks the algorithm if it matches
+    # when looking for a matche, we always compare all of them, no short
+    # circuiting
     def authenticated?(check_password)
       authed = false
       if algorithm.kind_of?(Array) then
         algorithm.each do |alg|
-          if alg.encode(check_password) == digest then
+          encoded = alg.encode(check_password)
+          if Algorithm.secure_compare(encoded, digest) then
             @algorithm = alg
             authed = true
-            break
           end
         end
       else
-        authed = digest == algorithm.encode(check_password)
+        encoded = algorithm.encode(check_password)
+        authed  = Algorithm.secure_compare(encoded, digest)
       end
       return authed
     end
 
+    # Internal: Returns the key of this entry
     def key
       return "#{user}"
     end
 
+    # Internal: Returns the file line for this entry
     def to_s
       "#{user}:#{digest}"
     end

data/lib/htauth/passwd_file.rb

@@ -1,25 +1,52 @@
 require 'stringio'
 require 'tempfile'
 
-require 'htauth/errors'
+require 'htauth/error'
 require 'htauth/file'
 require 'htauth/passwd_entry'
 
 module HTAuth
-  class PasswdFileError < StandardError ; end
-
-  # PasswdFile provides API style access to an +htpasswd+ produced file
+  # Public: An API for managing an 'htpasswd' file
+  #
+  # Examples
+  #
+  #   ::HTAuth::PasswdFile.open("my.passwd") do |pf|
+  #     pf.has_entry?('myuser', 'myrealm')
+  #     pf.add_or_update('someuser', 'myrealm', 'a password')
+  #     pf.delete('someolduser', 'myotherrealm')
+  #   end
+  #
   class PasswdFile < HTAuth::File
 
+    # Private: The class implementing a single entry in the PasswdFile
     ENTRY_KLASS = HTAuth::PasswdEntry
 
-    # does the entry the the specified username and realm exist in the file
+    # Public: Checks if the given username exists in the file
+    #
+    # username - the username to check
+    #
+    # Examples
+    #
+    #   passwd_file.has_entry?("myuser")
+    #   # => true
+    #
+    # Returns true or false if the username
     def has_entry?(username)
       test_entry = PasswdEntry.new(username)
       @entries.has_key?(test_entry.key)
     end
 
-    # remove an entry from the file
+    # Public: remove the given username from the file
+    # The file is not written to disk until #save! is called.
+    #
+    # username - the username to remove
+    #
+    # Examples
+    #
+    #   passwd_file.delete("myuser")
+    #   passwd_file.save!
+    #
+    # Returns nothing
     def delete(username)
       if has_entry?(username) then 
         ir = internal_record(username)
@@ -31,7 +58,27 @@ module HTAuth
       nil
     end
 
-    # add or update an entry as appropriate
+    # Public: Add or update the username entry with the new password and
+    # algorithm. This will add a new entry if the username does not exist in 
+    # the file. If the entry does exist in the file, then the password
+    # of the entry is updated to the new password / algorithm
+    #
+    # The file is not written to disk until #save! is called.
+    #
+    # username  - the username of the entry
+    # password  - the username of the entry
+    # algorithm - the algorithm to use (default: "md5"). Valid options are:
+    #             "md5", "sha1", "plaintext", or "crypt"
+    #
+    # Examples
+    #
+    #   passwd_file.add_or_update("newuser", "password", Algorithm::SHA1)
+    #   passwd_file.save!
+    #
+    #   passwd_file.add_or_update("newuser", "password")
+    #   passwd_file.save!
+    #
+    # Returns nothing.
     def add_or_update(username, password, algorithm = Algorithm::DEFAULT)
       if has_entry?(username) then
         update(username, password, algorithm)
@@ -40,7 +87,23 @@ module HTAuth
       end
     end
 
-    # add an new record.  raises an error if the entry exists.
+    # Public: Add a new record to the file.
+    #
+    # username  - the username of the entry
+    # password  - the username of the entry
+    # algorithm - the algorithm to use (default: "md5"). Valid options are:
+    #             "md5", "sha1", "plaintext", or "crypt"
+    #
+    # Examples
+    #
+    #   passwd_file.add("newuser", "password")
+    #   passwd_file.save!
+    #
+    #   passwd_file.add("newuser", "password", "sha1")
+    #   passwd_file.save!
+    #
+    # Returns nothing.
+    # Raises PasswdFileError if the give username already exists.
     def add(username, password, algorithm = Algorithm::DEFAULT)
       raise PasswdFileError, "Unable to add already existing user #{username}" if has_entry?(username)
       new_entry = PasswdEntry.new(username, password, algorithm)
@@ -51,7 +114,27 @@ module HTAuth
       return nil
     end
 
-    # update an already existing entry with a new password.  raises an error if the entry does not exist
+    # Public: Update an existing record in the file.
+    #
+    # By default, the same algorithm that already exists for the entry will be
+    # used with the new password. You may change the algorithm for an entry by
+    # setting the `algorithm` parameter.
+    #
+    # username  - the username of the entry
+    # password  - the username of the entry
+    # algorithm - the algorithm to use (default: "existing"). Valid options are:
+    #             "existing", "md5", "sha1", "plaintext", or "crypt"
+    #
+    # Examples
+    #
+    #   passwd_file.update("newuser", "password")
+    #   passwd_file.save!
+    #
+    #   passwd_file.update("newuser", "password", "sha1")
+    #   passwd_file.save!
+    #
+    # Returns nothing.
+    # Raises PasswdFileError if the give username does not exist.
     def update(username, password, algorithm = Algorithm::EXISTING)
       raise PasswdFileError, "Unable to update non-existent user #{username}" unless has_entry?(username)
       ir = internal_record(username)
@@ -62,14 +145,28 @@ module HTAuth
       return nil
     end
 
-    # fetches a copy of an entry from the file.  Updateing the entry returned from fetch will NOT
-    # propogate back to the file.
+    # Public: Returns a copy of then given PasswdEntry from the file.
+    #
+    # Updating the PasswdEntry instance returned by this method will NOT update
+    # the file. To update the file, use #update and #save!
+    #
+    # username - the username of the entry
+    #
+    # Examples
+    #
+    #   entry = password_file.fetch("myuser")
+    #
+    # Returns a PasswdEntry if the entry is found
+    # Returns nil if the entry is not found
     def fetch(username)
       return nil unless has_entry?(username)
       ir = internal_record(username)
       return ir['entry'].dup
     end
 
+    # Internal: returns the class used for each entry
+    #
+    # Returns a Class
     def entry_klass
       ENTRY_KLASS
     end

data/lib/htauth/plaintext.rb

@@ -1,8 +1,7 @@
 require 'htauth/algorithm'
 
 module HTAuth
-
-  # the plaintext algorithm, which does absolutly  nothing
+  # Internal: the plaintext algorithm, which does absolutly nothing
   class Plaintext < Algorithm
     # ignore parameters
     def initialize(params = {})

data/lib/htauth/sha1.rb

@@ -3,21 +3,21 @@ require 'digest/sha1'
 require 'base64'
 
 module HTAuth
+  # Internal: an implementation of the SHA based encoding algorithm
+  # as used in the apache htpasswd -s option
+  #
+  class Sha1 < Algorithm
 
-    # an implementation of the SHA based encoding algorithm 
-    # as used in the apache htpasswd -s option
-    class Sha1 < Algorithm
-        
-        # ignore the params
-        def initialize(params = {}) 
-        end
+    # ignore the params
+    def initialize(params = {}) 
+    end
 
-        def prefix
-            "{SHA}"
-        end
+    def prefix
+      "{SHA}"
+    end
 
-        def encode(password)
-            "#{prefix}#{Base64.encode64(::Digest::SHA1.digest(password)).strip}"
-        end
+    def encode(password)
+      "#{prefix}#{Base64.encode64(::Digest::SHA1.digest(password)).strip}"
     end
+  end
 end

data/lib/htauth/version.rb

@@ -1,21 +1,4 @@
 module HTAuth
-  VERSION = "1.2.0"
-  module Version
-    STRING  = HTAuth::VERSION
-    def to_a
-      STRING.split(".")
-    end
-
-    def to_s
-      STRING
-    end
-
-    module_function :to_a
-    module_function :to_s
-
-    MAJOR   = Version.to_a[0]
-    MINOR   = Version.to_a[1]
-    BUILD   = Version.to_a[2]
-
-  end
+  # Public: The version of the htauth library
+  VERSION = "2.0.0"
 end

data/spec/cli/digest_spec.rb

@@ -0,0 +1,150 @@
+require 'spec_helper'
+require 'htauth/cli/digest'
+require 'tempfile'
+
+describe HTAuth::CLI::Digest do
+
+  before(:each) do
+
+    # existing 
+    @tf = Tempfile.new("rpasswrd-digest-test")
+    @tf.write(IO.read(DIGEST_ORIGINAL_TEST_FILE))
+    @tf.close
+    @rdigest = HTAuth::CLI::Digest.new
+
+    # new file
+    @new_file = File.join(File.dirname(@tf.path), "new-testfile")
+
+    # rework stdout and stderr
+    @stdout = ConsoleIO.new
+    @old_stdout = $stdout
+    $stdout = @stdout
+
+    @stderr = ConsoleIO.new
+    @old_stderr = $stderr
+    $stderr = @stderr
+
+    @stdin = ConsoleIO.new
+    @old_stdin = $stdin
+    $stdin = @stdin
+  end
+
+  after(:each) do
+    @tf.close(true)
+    $stderr = @old_stderr
+    $stdout = @old_stdout
+    $stdin = @old_stdin
+    File.unlink(@new_file) if File.exist?(@new_file)
+  end
+
+  it "displays help appropriately" do
+    begin
+      @rdigest.run([ "-h" ])
+    rescue SystemExit => se
+      se.status.must_equal 1
+      @stdout.string.must_match( /passwordfile realm username/m )
+    end
+  end
+
+  it "displays the version appropriately" do
+    begin
+      @rdigest.run([ "--version" ])
+    rescue SystemExit => se
+      se.status.must_equal 1
+      @stdout.string.must_match( /version #{HTAuth::VERSION}/ )
+    end
+  end
+
+  it "creates a new file with one entries" do
+    begin
+      @stdin.puts "b secret"
+      @stdin.puts "b secret"
+      @stdin.rewind
+      @rdigest.run([ "-c", @new_file, "htauth", "bob" ])
+    rescue SystemExit => se
+      se.status.must_equal 0
+      IO.read(@new_file).must_equal IO.readlines(DIGEST_ORIGINAL_TEST_FILE).first
+    end
+  end
+
+  it "truncates an exiting file if told to create a new file" do
+    begin
+      @stdin.puts "b secret"
+      @stdin.puts "b secret"
+      @stdin.rewind
+      @rdigest.run([ "-c", @tf.path, "htauth", "bob"])
+    rescue SystemExit => se
+      se.status.must_equal 0
+      IO.read(@tf.path).must_equal IO.read(DIGEST_DELETE_TEST_FILE)
+    end
+  end
+
+  it "adds an entry to an existing file" do
+    begin
+      @stdin.puts "c secret"
+      @stdin.puts "c secret"
+      @stdin.rewind
+      @rdigest.run([ @tf.path, "htauth-new", "charlie" ])
+    rescue SystemExit => se
+      se.status.must_equal 0
+      IO.read(@tf.path).must_equal IO.read(DIGEST_ADD_TEST_FILE)
+    end
+  end
+
+  it "updates an entry in an existing file" do
+    begin
+      @stdin.puts "a new secret"
+      @stdin.puts "a new secret"
+      @stdin.rewind
+      @rdigest.run([ @tf.path, "htauth", "alice" ])
+    rescue SystemExit => se
+      @stderr.string.must_equal ""
+      se.status.must_equal 0
+      IO.read(@tf.path).must_equal IO.read(DIGEST_UPDATE_TEST_FILE)
+    end
+  end
+
+  it "deletes an entry in an existing file" do
+    begin
+      @rdigest.run([ "-d", @tf.path, "htauth", "alice" ])
+    rescue SystemExit => se
+      @stderr.string.must_equal ""
+      se.status.must_equal 0
+      IO.read(@tf.path).must_equal IO.read(DIGEST_DELETE_TEST_FILE)
+    end
+  end
+
+  it "has an error if it does not have permissions on the file" do
+    begin
+      @stdin.puts "a secret"
+      @stdin.puts "a secret"
+      @stdin.rewind
+      @rdigest.run([ "-c", "/etc/you-cannot-create-me", "htauth", "alice"])
+    rescue SystemExit => se
+      @stderr.string.must_match( %r{Could not open password file /etc/you-cannot-create-me}m )
+      se.status.must_equal 1
+    end
+  end
+
+  it "has an error if the input passwords do not match" do
+    begin
+      @stdin.puts "a secret"
+      @stdin.puts "a bad secret"
+      @stdin.rewind
+      @rdigest.run([ @tf.path, "htauth", "alice"])
+    rescue SystemExit => se
+      @stderr.string.must_match( /They don't match, sorry./m )
+      se.status.must_equal 1
+    end
+  end
+
+  it "has an error if the options are incorrect" do
+    begin
+      @rdigest.run(["--blah"])
+    rescue SystemExit => se
+      @stderr.string.must_match( /ERROR:/m )
+      se.status.must_equal 1
+    end
+  end
+
+end