htauth 2.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a392e544654ec732a878871166ba48129a72dc8e7d2b3b9e1ed37d99117546b9
-  data.tar.gz: fb244f0b94603e5829d36d10e1309d98608a584c1bc8ea3a3d95f60f9950b7fb
+  metadata.gz: bf3dca478538f6a659cfe1cbe39b0688782e34f606cba0b116a63a87c42f022e
+  data.tar.gz: 83508be980a643ec2a481582ecc8ad02f3f8271b2d34359ab26bad2369d4eddd
 SHA512:
-  metadata.gz: 3350108830c0ce7bb7e406ec2d449c89eaf3ce1047f095cab78cffe8c197fb03eb9a5ffe7ad1b782e6d15c1ed88017ef96cb48e87cd8e91993454e00bc1fffda
-  data.tar.gz: 3b4183cd67ab796c5de2c2fcee847a94ab7d83e925b5283640bd7718274667e141d1618a10f927cf5c6e70cc5a667c284577d83d449a7566770ea60e5a2bc20e
+  metadata.gz: 48c8f83ca6e2c893731098c076680c37eeb6ff8fe1bde0589957c56239f8239cdb2e8fad01ea2278c6c10f25879e9adc4ba43385f6250435c08207d7b9381a87
+  data.tar.gz: a059b27747b6ca12201171500c8f08672b2b378d4e80c83ed5caa9725e009f0366470607e756c02905c253f9c2c4dd173aa58760c7978238a3862c85b038b431

data/HISTORY.md

@@ -1,5 +1,25 @@
 # Changelog
-## Version 2.2.0 - 2023-02-XX
+## Version 3.0.0 - 2026-05-23
+
+* Modernize project structure
+* Bump minimum Ruby version from 2.3.0 to 3.0.0
+* Add rubocop for code linting with multiple plugins
+* Rename `is_entry?`/`is_entry_for?` methods to `entry?`/`entry_for?` (Ruby naming conventions)
+* Update CI build matrix: Ruby 3.3, 3.4, 4.0, JRuby 10.1, TruffleRuby 34.0
+* Remove Ruby 3.2 from build matrix
+* Move development dependencies from gemspec to Gemfile
+* Add `ostruct` as a runtime dependency
+* Remove test files from gem package
+* Rename `LICENSE` to `LICENSE.txt`
+* Apply rubocop autocorrections across all source and spec files
+
+## Version 2.3.0 - 2024-02-03
+
+* Add support for argon2 encryption [#18](https://github.com/copiousfreetime/htauth/pull/18)
+* Update supported ruby version, now supporting ruby 3.x only
+* Semaphore updates
+
+## Version 2.2.0 - 2023-02-06
 
 * Update ruby versions
 * Add to sempahore for CI

data/Manifest.txt

@@ -1,13 +1,14 @@
 CONTRIBUTING.md
 HISTORY.md
-LICENSE
+LICENSE.txt
 Manifest.txt
 README.md
-Rakefile
-bin/htdigest-ruby
-bin/htpasswd-ruby
+exe/htdigest-ruby
+exe/htpasswd-ruby
+htauth.gemspec
 lib/htauth.rb
 lib/htauth/algorithm.rb
+lib/htauth/argon2.rb
 lib/htauth/bcrypt.rb
 lib/htauth/cli.rb
 lib/htauth/cli/digest.rb
@@ -26,26 +27,3 @@ lib/htauth/passwd_file.rb
 lib/htauth/plaintext.rb
 lib/htauth/sha1.rb
 lib/htauth/version.rb
-spec/algorithm_spec.rb
-spec/bcrypt_spec.rb
-spec/cli/digest_spec.rb
-spec/cli/passwd_spec.rb
-spec/crypt_spec.rb
-spec/digest_entry_spec.rb
-spec/digest_file_spec.rb
-spec/md5_spec.rb
-spec/passwd_entry_spec.rb
-spec/passwd_file_spec.rb
-spec/plaintext_spec.rb
-spec/sha1_spec.rb
-spec/spec_helper.rb
-spec/test.add.digest
-spec/test.add.passwd
-spec/test.delete.digest
-spec/test.delete.passwd
-spec/test.original.digest
-spec/test.original.passwd
-spec/test.update.digest
-spec/test.update.passwd
-tasks/default.rake
-tasks/this.rb

data/README.md

@@ -7,25 +7,45 @@
 
 ## DESCRIPTION
 
-HTAuth is a pure ruby replacement for the Apache support programs htdigest and
-htpasswd.  Command line and API access are provided for access to htdigest and
-htpasswd files.
+HTAuth provides an API and commandline tools for managing Apache/httpd style
+htpasswd and htdigest files.
 
 ## FEATURES
 
-HTAuth provides to drop in commands *htdigest-ruby* and *htpasswd-ruby* that
-can manipulate the digest and passwd files in the same manner as Apache's
-original commands.
+HTAuth provides an API allowing direct manipulation of Apache/httpd style
+`htdigest` and `htpasswd` files. Supporting full programmatic manipulation and
+authentication of user credentials.
 
-*htdigest-ruby* and *htpasswd-ruby* are command line compatible with *htdigest*
-and *htpasswd*.  They support the same exact same command line options as the
-originals, and have some extras.
+HTAuth also includes drop-in, commandline compatible replacements for the Apache
+utilities `htpasswd` and `htdigest` with the respective `htpasswd-ruby` and
+`htdigest-ruby` commands.
 
-Additionally, you can access all the functionality of *htdigest-ruby* and
-*htpasswd-ruby* through an API.
+Additionally, support for the [argon2](https://github.com/technion/ruby-argon2)
+password hashing algorithm is provided for most platforms.
 
 ## SYNOPSIS
 
+### API Usage
+
+    HTAuth::DigestFile.open("some.htdigest") do |df|
+      df.add_or_update('someuser', 'myrealm', 'a password')
+      df.delete('someolduser', 'myotherrealm')
+    end
+
+    HTAuth::PasswdFile.open("some.htpasswd", HTAuth::File::CREATE) do |pf|
+      pf.add('someuser', 'a password', 'md5')
+      pf.add('someotheruser', 'a different password', 'sha1')
+    end
+
+    HTAuth::PasswdFile.open("some.htpasswd", HTAuth::File::ALTER) do |pf|
+      pf.update('someuser', 'a password', 'bcrypt')
+    end
+
+    HTAuth::PasswdFile.open("some.htpasswd") do |pf|
+      pf.authenticated?('someuser', 'a password')
+    end
+
+
 ### htpasswd-ruby command line application
 
     Usage:
@@ -35,7 +55,8 @@ Additionally, you can access all the functionality of *htdigest-ruby* and
             htpasswd-ruby -n[imBdps] [-C cost] username
             htpasswd-ruby -nb[mBdps] [-C cost] username password
 
-        -b, --batch      Batch mode, get the password from the command line, rather than prompt
+            --argon2     Force argon2 encryption of the password.
+        -b, --batch      Batch mode, get the password from the command line, rather than prompt.
         -B, --bcrypt     Force bcrypt encryption of the password.
         -C, --cost COST  Set the computing time used for the bcrypt algorithm
                          (higher is more secure but slower, default: 5, valid: 4 to 31).
@@ -49,9 +70,7 @@ Additionally, you can access all the functionality of *htdigest-ruby* and
         -p, --plaintext  Do not encrypt the password (plaintext).
         -s, --sha1       Force SHA encryption of the password.
         -v, --version    Show version info.
-            --verify     Verify password for the specified user
-
-    The SHA algorithm does not use a salt and is less secure than the MD5 algorithm.
+            --verify     Verify password for the specified user.
 
 ### htdigest-ruby command line application
 
@@ -61,30 +80,31 @@ Additionally, you can access all the functionality of *htdigest-ruby* and
         -h, --help     Display this help.
         -v, --version  Show version info.
 
-### API Usage
+## Supported Hash Algorithms
 
-    HTAuth::DigestFile.open("some.htdigest") do |df|
-      df.add_or_update('someuser', 'myrealm', 'a password')
-      df.delete('someolduser', 'myotherrealm')
-    end
+Out of the box, `htauth` supports the classic algorithms that ship with Apache
+`htpasswd`.
 
-    HTAuth::PasswdFile.open("some.htpasswd", HTAuth::File::CREATE) do |pf|
-      pf.add('someuser', 'a password', 'md5')
-      pf.add('someotheruser', 'a different password', 'sha1')
-    end
+- Built in
+    - Generally accepted
+        - MD5 (default for compatibility reasons)
+        - bcrypt (probably the better choice)
 
-    HTAuth::PasswdFile.open("some.htpasswd", HTAuth::File::ALTER) do |pf|
-      pf.update('someuser', 'a password', 'bcrypt')
-    end
+    - **Not Recommended** - available only for backwards compatibility with `htpasswd`
+        - SHA1
+        - crypt
+        - plaintext
 
-    HTAuth::PasswdFile.open("some.htpasswd") do |pf|
-      pf.authenticated?('someuser', 'a password')
-    end
+- Available with the installation of additional libraries:
+    - argon2 - to use, add `gem 'argon2'` to your `Gemfile`. `argon2` will
+      now be a valid algorithm to use in `HTAuth::PasswdFile` API. Currently
+      argon2 is not supported on windows as the upstream `argon2` gem does not
+      support windows.
 
 ## CREDITS
 
 * [The Apache Software Foundation](http://www.apache.org/)
-* all the folks who contributed to htdigest and htpassword
+* all the folks who contributed to htdigest and htpasswd
 
 ## MIT LICENSE
 

data/exe/htdigest-ruby

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+begin
+  require "htauth/cli/digest"
+rescue LoadError
+  path = File.expand_path(File.join(File.dirname(__FILE__), "..", "lib"))
+  raise if $LOAD_PATH.include?(path)
+
+  $LOAD_PATH << path
+  retry
+end
+
+HTAuth::CLI::Digest.new.run(ARGV, ENV)

data/exe/htpasswd-ruby

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+begin
+  require "htauth/cli/passwd"
+rescue LoadError
+  path = File.expand_path(File.join(File.dirname(__FILE__), "..", "lib"))
+  raise if $LOAD_PATH.include?(path)
+
+  $LOAD_PATH << path
+  retry
+end
+
+HTAuth::CLI::Passwd.new.run(ARGV, ENV)

data/htauth.gemspec

@@ -0,0 +1,33 @@
+# DO NOT EDIT - This file is automatically generated
+# Make changes to Manifest.txt and/or Rakefile and regenerate
+# -*- encoding: utf-8 -*-
+# stub: htauth 3.0.0 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "htauth".freeze
+  s.version = "3.0.0".freeze
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
+  s.metadata = { "bug_tracker_uri" => "https://github.com/copiousfreetime/htauth/issues", "changelog_uri" => "https://github.com/copiousfreetime/htauth/blob/master/HISTORY.md", "homepage_uri" => "https://github.com/copiousfreetime/htauth", "source_code_uri" => "https://github.com/copiousfreetime/htauth" } if s.respond_to? :metadata=
+  s.require_paths = ["lib".freeze]
+  s.authors = ["Jeremy Hinegardner".freeze]
+  s.bindir = "exe".freeze
+  s.date = "2026-05-23"
+  s.description = "HTAuth provides an API and commandline tools for managing Apache/httpd style htpasswd and htdigest files.".freeze
+  s.email = "jeremy@copiousfreetime.org".freeze
+  s.executables = ["htdigest-ruby".freeze, "htpasswd-ruby".freeze]
+  s.extra_rdoc_files = ["CONTRIBUTING.md".freeze, "HISTORY.md".freeze, "LICENSE.txt".freeze, "Manifest.txt".freeze, "README.md".freeze]
+  s.files = ["CONTRIBUTING.md".freeze, "HISTORY.md".freeze, "LICENSE.txt".freeze, "Manifest.txt".freeze, "README.md".freeze, "exe/htdigest-ruby".freeze, "exe/htpasswd-ruby".freeze, "htauth.gemspec".freeze, "lib/htauth.rb".freeze, "lib/htauth/algorithm.rb".freeze, "lib/htauth/argon2.rb".freeze, "lib/htauth/bcrypt.rb".freeze, "lib/htauth/cli.rb".freeze, "lib/htauth/cli/digest.rb".freeze, "lib/htauth/cli/passwd.rb".freeze, "lib/htauth/console.rb".freeze, "lib/htauth/crypt.rb".freeze, "lib/htauth/descendant_tracker.rb".freeze, "lib/htauth/digest_entry.rb".freeze, "lib/htauth/digest_file.rb".freeze, "lib/htauth/entry.rb".freeze, "lib/htauth/error.rb".freeze, "lib/htauth/file.rb".freeze, "lib/htauth/md5.rb".freeze, "lib/htauth/passwd_entry.rb".freeze, "lib/htauth/passwd_file.rb".freeze, "lib/htauth/plaintext.rb".freeze, "lib/htauth/sha1.rb".freeze, "lib/htauth/version.rb".freeze]
+  s.homepage = "http://github.com/copiousfreetime/htauth".freeze
+  s.licenses = ["MIT".freeze]
+  s.rdoc_options = ["--main".freeze, "README.md".freeze, "--markup".freeze, "tomdoc".freeze]
+  s.required_ruby_version = Gem::Requirement.new(">= 3.0.0".freeze)
+  s.rubygems_version = "4.0.10".freeze
+  s.summary = "HTAuth provides an API and commandline tools for managing Apache/httpd style htpasswd and htdigest files.".freeze
+
+  s.specification_version = 4
+
+  s.add_runtime_dependency(%q<bcrypt>.freeze, ["~> 3.1".freeze])
+  s.add_runtime_dependency(%q<base64>.freeze, ["~> 0.2".freeze])
+  s.add_runtime_dependency(%q<ostruct>.freeze, ["~> 0.6".freeze])
+end

data/lib/htauth/algorithm.rb

@@ -1,48 +1,50 @@
-require 'htauth/error'
-require 'htauth/descendant_tracker'
-require 'securerandom'
+# frozen_string_literal: true
+
+require "htauth/error"
+require "htauth/descendant_tracker"
+require "securerandom"
 module HTAuth
   class InvalidAlgorithmError < Error; end
 
   # Internal: Base class all the password algorithms derive from
   #
   class Algorithm
-
     extend DescendantTracker
 
-    SALT_CHARS    = (%w[ . / ] + ("0".."9").to_a + ('A'..'Z').to_a + ('a'..'z').to_a).freeze
+    SALT_CHARS    = (%w[. /] + ("0".."9").to_a + ("A".."Z").to_a + ("a".."z").to_a).freeze
     SALT_LENGTH   = 8
 
+    # Public: flag for the argon2 algorithm
+    ARGON2        = "argon2"
     # Public: flag for the bcrypt algorithm
-    BCRYPT        = "bcrypt".freeze
+    BCRYPT        = "bcrypt"
     # Public: flag for the md5 algorithm
-    MD5           = "md5".freeze
+    MD5           = "md5"
     # Public: flag for the sha1 algorithm
-    SHA1          = "sha1".freeze
+    SHA1          = "sha1"
     # Public: flag for the plaintext algorithm
-    PLAINTEXT     = "plaintext".freeze
+    PLAINTEXT     = "plaintext"
     # Public: flag for the crypt algorithm
-    CRYPT         = "crypt".freeze
+    CRYPT         = "crypt"
 
     # Public: flag for the default algorithm
     DEFAULT       = MD5
 
     # Public: flag to indicate using the existing algorithm of the entry
-    EXISTING      = "existing".freeze
-
+    EXISTING      = "existing"
 
     class << self
       def algorithm_name
-        self.name.split("::").last.downcase
+        name.split("::").last.downcase
       end
 
       def algorithm_from_name(a_name, params = {})
         found = children.find { |c| c.algorithm_name == a_name }
-        if !found then
-          names = children.map { |c| c.algorithm_name }
+        unless found
+          names = children.map(&:algorithm_name)
           raise InvalidAlgorithmError, "`#{a_name}' is an unknown encryption algorithm, use one of #{names.join(', ')}"
         end
-        return found.new(params)
+        found.new(params)
       end
 
       # NOTE: if it is plaintext, and the length is 13 - it may matched crypt
@@ -55,13 +57,13 @@ module HTAuth
 
         raise InvalidAlgorithmError, "unknown encryption algorithm used for `#{password_field}`" if match.nil?
 
-        return match.new(:existing => password_field)
+        match.new(existing: password_field)
       end
 
       # Internal: Does this class handle this type of password entry
       #
       def handles?(password_entry)
-        raise NotImplementedError, "#{self.name} must implement #{self.name}.handles?(password_entry)"
+        raise NotImplementedError, "#{name} must implement #{name}.handles?(password_entry)"
       end
 
       # Internal: Constant time string comparison.
@@ -72,35 +74,46 @@ module HTAuth
       # that have already been processed by HMAC. This should not be used
       # on variable length plaintext strings because it could leak length info
       # via timing attacks.
-      def secure_compare(a, b)
-        return false unless a.bytesize == b.bytesize
+      def secure_compare(lhs, rhs)
+        return false unless lhs.bytesize == rhs.bytesize
 
-        l = a.unpack("C*")
+        l = lhs.unpack("C*")
 
-        r, i = 0, -1
-        b.each_byte { |v| r |= v ^ l[i+=1] }
-        r == 0
+        r = 0
+        i = -1
+        rhs.each_byte { |v| r |= v ^ l[i += 1] }
+        r.zero?
       end
     end
 
     # Internal
-    def encode(password) ; end
+    def encode(password)
+      raise NotImplementedError, "#{self.class.name} must implement #{self.class.name}.encode(password)"
+    end
+
+    # Internal: Does the given password match the digest, the default just
+    # encodes and secure compares the result, different algorithms may overide
+    # this method
+    def verify_password?(password, digest)
+      encoded = encode(password)
+      self.class.secure_compare(encoded, digest)
+    end
 
     # Internal: 8 bytes of random items from SALT_CHARS
     def gen_salt(length = SALT_LENGTH)
-      Array.new(length) { SALT_CHARS.sample }.join('')
+      Array.new(length) { SALT_CHARS.sample }.join
     end
 
     # Internal: this is not the Base64 encoding, this is the to64()
     # method from the Apache Portable Runtime (APR) library
     # https://github.com/apache/apr/blob/trunk/crypto/apr_md5.c#L493-L502
-    def to_64(number, rounds)
+    def to64(number, rounds)
       r = StringIO.new
-      rounds.times do |x|
+      rounds.times do |_x|
         r.print(SALT_CHARS[number % 64])
         number >>= 6
       end
-      return r.string
+      r.string
     end
   end
 end

data/lib/htauth/argon2.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "htauth/algorithm"
+begin
+  require "argon2"
+rescue LoadError
+end
+
+module HTAuth
+  # Internal:  Support of the argon2id algorithm and password format.
+  class Argon2 < Algorithm
+    # Internal: Error class when argon2 is specified on windows
+    class NotSupportedError < ::HTAuth::InvalidAlgorithmError
+      def message
+        [
+          "Unfortunately Argon2 passwords are not supported on `#{RUBY_PLATFORM} at this time.",
+          "This because the upstream argon2 gem does not support windows.",
+        ].join(" ")
+      end
+    end
+
+    # Internal: Error class when argon2 is not installed
+    class NotInstalledError < ::HTAuth::InvalidAlgorithmError
+      def message
+        "Argon2 passwords are supported if the `argon2' gem is installed. Add `gem 'argon2', '~> 2.3'` to your Gemfile"
+      end
+    end
+
+    # from upstream, used to help make a nice error message if its not installed
+    # https://github.com/technion/ruby-argon2/blob/3388d7e05e8b486ea4ba8bd2aeb1e9988f025f13/lib/argon2/hash_format.rb#L45
+    PREFIX = /^\$argon2(id?|d).{,113}/
+    ARGON2_GEM_INSTALLED = defined?(::Argon2)
+
+    def self.supported?
+      !::Gem.win_platform?
+    end
+
+    def self.ensure_available!
+      raise NotSupportedError unless supported?
+      raise NotInstalledError unless ARGON2_GEM_INSTALLED
+    end
+
+    attr_accessor :options
+
+    def self.handles?(password_entry)
+      return false unless PREFIX.match?(password_entry)
+
+      ensure_available!
+
+      ::Argon2::Password.valid_hash?(password_entry)
+    end
+
+    def self.extract_options_from_existing_password_field(existing)
+      hash_format = ::Argon2::HashFormat.new(existing)
+
+      # m_cost on the input is the 2**m_cost, but in the hash its the number of
+      # bytes, so need to convert it back to a power of 2, which is the
+      # log2(m_cost)
+
+      {
+        t_cost: hash_format.t_cost,
+        m_cost: ::Math.log2(hash_format.m_cost).floor,
+        p_cost: hash_format.p_cost,
+      }
+    end
+
+    def initialize(params = { profile: :rfc_9106_low_memory })
+      super()
+      self.class.ensure_available!
+      @options = if (existing = params["existing"] || params[:existing])
+                   self.class.extract_options_from_existing_password_field(existing)
+                 else
+                   params
+                 end
+    end
+
+    def encode(password)
+      argon2 = ::Argon2::Password.new(options)
+      argon2.create(password)
+    end
+
+    def verify_password?(password, digest)
+      ::Argon2::Password.verify_password(password, digest)
+    end
+  end
+end

data/lib/htauth/bcrypt.rb

@@ -1,18 +1,18 @@
-require 'htauth/algorithm'
-require 'bcrypt'
+# frozen_string_literal: true
+
+require "htauth/algorithm"
+require "bcrypt"
 
 module HTAuth
   # Internal: an implementation of the Bcrypt based encoding algorithm
   # as used in the apache htpasswd -B option
-
   class Bcrypt < Algorithm
-
     attr_accessor :cost
 
     DEFAULT_APACHE_COST = 5 # this is the default cost from htpasswd
 
     def self.handles?(password_entry)
-      return ::BCrypt::Password.valid_hash?(password_entry)
+      ::BCrypt::Password.valid_hash?(password_entry)
     end
 
     def self.extract_cost_from_existing_password_field(existing)
@@ -21,15 +21,21 @@ module HTAuth
     end
 
     def initialize(params = {})
-      if existing = (params['existing'] || params[:existing]) then
-        @cost = self.class.extract_cost_from_existing_password_field(existing)
-      else
-        @cost = params['cost'] || params[:cost] || DEFAULT_APACHE_COST
-      end
+      super()
+      @cost = if (existing = params["existing"] || params[:existing])
+                self.class.extract_cost_from_existing_password_field(existing)
+              else
+                params["cost"] || params[:cost] || DEFAULT_APACHE_COST
+              end
     end
 
     def encode(password)
-      ::BCrypt::Password.create(password, :cost => cost)
+      ::BCrypt::Password.create(password, cost: cost)
+    end
+
+    def verify_password?(password, digest)
+      bc = ::BCrypt::Password.new(digest)
+      bc.is_password?(password)
     end
   end
 end