passlib 0.1.0

data/lib/passlib/internal/dsl.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Passlib::Internal
+  module DSL
+    Config = Passlib::Configuration::Passlib
+
+    def identifier(value = nil)
+      @identifier = value if value
+      @identifier ||= name[/\w+$/].downcase.to_sym
+    end
+
+    private
+
+    def register(*keys, mcf: nil, pattern: nil)
+      if keys.empty?
+        keys = [identifier]
+      else
+        @identifier ||= keys.first
+      end
+
+      keys.each { Register::IDENTIFIERS[it] = self if it }
+      Array(mcf).each { Register::MFC_IDS[it.to_s] = self if it }
+      Array(pattern).each { Register::PATTERNS[it] = self if it }
+    end
+
+    def external(*) = extend Dependency[*]
+
+    def config(input, **options)
+      case input
+      when configuration_class then base_config          = input
+      when Hash                then options, base_config = input.merge(options), config_base
+      when Config              then base_config          = input.respond_to?(identifier) ? input.public_send(identifier) : input
+      when nil                 then base_config          = config_base
+      else raise ArgumentError, "invalid configuration: #{input.inspect}"
+      end
+      return base_config if options.empty?
+      configuration_class.new(base_config, options)
+    end
+
+    def config_base
+      Passlib.configuration.respond_to?(identifier) ? Passlib.configuration.public_send(identifier) : Passlib.configuration
+    end
+
+    def configuration_class
+      @configuration_class ||= begin
+        demodulize = name[/\w+$/]
+        unless Passlib::Configuration.const_defined?(demodulize, false)
+          Passlib::Configuration.const_set(demodulize, Class.new(Passlib::Configuration))
+        end
+        config_class = Passlib::Configuration.const_get(demodulize)
+        Config.option(identifier, config_class.new)
+        config_class
+      end
+    end
+
+    def option(...)  = configuration_class.option(...)
+    def options(...) = configuration_class.options(...)
+  end
+end

data/lib/passlib/internal/register.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Passlib::Internal
+  module Register
+    IDENTIFIERS ||= {}
+    MFC_IDS     ||= {}
+    LDAP_IDS    ||= {}
+    PATTERNS    ||= {}
+  end
+end

data/lib/passlib/internal.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Passlib
+  module Internal
+    Dir.glob("internal/*.rb", base: __dir__) { require_relative it }
+    extend self
+
+    def decode64(input)    = input.unpack1("m")
+    def encode64(input)    = [input].pack("m0").sub(/=+\n*\z/, "")
+    def encode_ab64(data)  = [data].pack("m0").delete("=").tr("+", ".")
+    def decode_ab64(str)   = (str.tr(".", "+") + "=" * ((-str.length) % 4)).unpack1("m")
+    def random_bytes(size) = OpenSSL::Random.random_bytes(size)
+
+    def mcf_params(string)
+      string
+        .scan(/(?<=\$|,)([a-z]+)=([^,\$]+)(?=\$|,)/)
+        .to_h { [_1.to_sym, _2 =~ /^\d+$/ ? _2.to_i : _2] }
+    end
+  end
+
+  private_constant :Internal
+end

data/lib/passlib/ldap_digest.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Passlib
+  # Handles LDAP RFC 2307 digest password hashes.
+  #
+  # Supports plain and salted variants for MD5, SHA-1, SHA-256, SHA-512,
+  # SHA3-256, and SHA3-512. MD5 and SHA-1 hashes may be stored in hex encoding
+  # (as produced by some LDAP implementations) or standard base64, both are
+  # detected automatically on load and preserved on round-trips.
+  #
+  # Scheme names and their corresponding LDAP prefix:
+  # - +MD5+ / +SMD5+ (salted)
+  # - +SHA+ / +SSHA+ (salted)
+  # - +SHA256+ / +SSHA256+ (salted)
+  # - +SHA512+ / +SSHA512+ (salted)
+  # - +SHA3-256+ / +SSHA3-256+ (salted)
+  # - +SHA3-512+ / +SSHA3-512+ (salted)
+  #
+  # Hash format: +{SSHA512}base64data+ (or +{MD5}hexdata+ for hex-encoded MD5/SHA)
+  #
+  # @example
+  #   hash = Passlib::LdapDigest.create("hunter2", variant: "SSHA512")
+  #   hash.verify("hunter2")  # => true
+  #   hash.to_s               # => "{SSHA512}..."
+  #
+  # @!method self.create(secret, **options)
+  #   Creates a new LDAP digest hash.
+  #   @param secret [String] the plaintext password
+  #   @option options [String, Symbol] :variant LDAP scheme name — one of +"MD5"+, +"SMD5"+,
+  #     +"SHA"+, +"SSHA"+, +"SHA256"+, +"SSHA256"+, +"SHA512"+, +"SSHA512"+,
+  #     +"SHA3-256"+, +"SSHA3-256"+, +"SHA3-512"+, +"SSHA3-512"+;
+  #     case-insensitive, symbols accepted, underscores may be used instead of dashes
+  #     (default: +"SSHA512"+)
+  #   @option options [String]  :salt    raw binary salt, only used for salted schemes
+  #     (default: random, 4 bytes for MD5/SHA-1, 8 bytes for others)
+  #   @option options [Boolean] :hex     encode the output as hex instead of base64,
+  #     only applicable to MD5 and SHA schemes (default: false)
+  #   @return [LdapDigest]
+  class LdapDigest < Password
+    SCHEMES = {
+      "MD5"       => { digest: "MD5",      size: 16, salted: false },
+      "SHA"       => { digest: "SHA1",     size: 20, salted: false },
+      "SHA256"    => { digest: "SHA256",   size: 32, salted: false },
+      "SHA512"    => { digest: "SHA512",   size: 64, salted: false },
+      "SHA3-256"  => { digest: "SHA3-256", size: 32, salted: false },
+      "SHA3-512"  => { digest: "SHA3-512", size: 64, salted: false },
+      "SMD5"      => { digest: "MD5",      size: 16, salted: true, salt_size: 4 },
+      "SSHA"      => { digest: "SHA1",     size: 20, salted: true, salt_size: 4 },
+      "SSHA256"   => { digest: "SHA256",   size: 32, salted: true, salt_size: 8 },
+      "SSHA512"   => { digest: "SHA512",   size: 64, salted: true, salt_size: 8 },
+      "SSHA3-256" => { digest: "SHA3-256", size: 32, salted: true, salt_size: 8 },
+      "SSHA3-512" => { digest: "SHA3-512", size: 64, salted: true, salt_size: 8 },
+    }.freeze
+
+    LOAD_PATTERN = /\A\{([A-Z0-9-]+)\}([A-Za-z0-9+\/=]+)\z/i
+    DEFAULT      = "SSHA512"
+    HEX_SCHEMES  = %w[MD5 SHA].freeze
+
+    private_constant :SCHEMES, :LOAD_PATTERN, :DEFAULT, :HEX_SCHEMES
+
+    # Register all scheme names (including hyphenated SHA3 variants) so the
+    # updated LDAP auto-detection regex can match them directly.
+    SCHEMES.each_key { Internal::Register::LDAP_IDS[_1] = self }
+    register :ldap_digest
+
+    options :variant, :salt, :hex
+
+    # @param secret [String] the plaintext password to re-hash
+    # @return [LdapDigest] a new instance hashed with the same scheme, salt, and encoding
+    def create_comparable(secret) = self.class.create(secret, variant: @variant, salt: @salt, hex: @hex)
+
+    def upgrade?
+      configured = normalize_variant(config.variant)
+      @variant != configured
+    end
+
+    private
+
+    def normalize_variant(input)
+      return DEFAULT unless input
+      input.to_s.upcase.tr("_", "-")
+    end
+
+    def create(secret)
+      @variant = normalize_variant(config.variant)
+      scheme   = SCHEMES[@variant] or raise ArgumentError, "unknown LDAP scheme: #{@variant.inspect}"
+      @salt    = config.salt || (scheme[:salted] ? Internal.random_bytes(scheme[:salt_size]) : nil)
+      @hex     = config.hex
+      checksum = OpenSSL::Digest.digest(scheme[:digest], secret.to_s.b + @salt.to_s.b)
+      data     = scheme[:salted] ? checksum + @salt : checksum
+      @hex ? "{#{@variant}}#{data.unpack1("H*")}" : "{#{@variant}}#{[data].pack("m0")}"
+    end
+
+    def load(string)
+      m        = LOAD_PATTERN.match(string) or raise UnknownHashFormat, "invalid LDAP hash: #{string.inspect}"
+      @variant = normalize_variant(m[1])
+      scheme   = SCHEMES[@variant] or raise UnknownHashFormat, "unknown LDAP scheme: #{@variant.inspect}"
+      @hex     = HEX_SCHEMES.include?(@variant) &&
+                 m[2].length == scheme[:size] * 2 &&
+                 m[2].match?(/\A[0-9a-f]+\z/i)
+      raw      = @hex ? [m[2]].pack("H*") : m[2].unpack1("m")
+      @salt    = raw[scheme[:size]..] if scheme[:salted]
+      string
+    end
+  end
+end

data/lib/passlib/md5_crypt.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Passlib
+  # Handles MD5-crypt and Apache MD5-crypt password hashing.
+  #
+  # MD5-crypt was designed by Poul-Henning Kamp for FreeBSD in 1994. It runs
+  # 1000 rounds of a complex MD5-based mixing function and was widely deployed
+  # on Linux systems as the default password scheme. Apache's variant is
+  # identical except for using a different MCF identifier.
+  #
+  # Two MCF identifiers are recognized:
+  # - +$1$+ — standard MD5-crypt (FreeBSD/Linux)
+  # - +$apr1$+ — Apache APR variant (functionally identical, different prefix)
+  #
+  # New hashes created via +MD5Crypt.create+ use +$1$+. To create APR hashes,
+  # pass +variant: :apr+.
+  #
+  # Hash format: +$1$<salt>$<checksum>+ or +$apr1$<salt>$<checksum>+
+  #
+  # - +salt+ — 0-8 characters from +./0-9A-Za-z+ (default: 8 random characters)
+  # - +checksum+ — 22 characters from +./0-9A-Za-z+
+  #
+  # This format is compatible with the
+  # {https://passlib.readthedocs.io/en/stable/lib/passlib.hash.md5_crypt.html
+  # md5_crypt} and
+  # {https://passlib.readthedocs.io/en/stable/lib/passlib.hash.apr_md5_crypt.html
+  # apr_md5_crypt} as implemented in Python's passlib.
+  #
+  # @note MD5-crypt is a legacy algorithm with a fixed, low round count.
+  #   It is supported here for verifying existing hashes and migrating users
+  #   to a stronger scheme. Do not use it for new hashes.
+  #
+  # @example
+  #   hash = Passlib::MD5Crypt.create("hunter2")
+  #   hash.verify("hunter2")     # => true
+  #   hash.to_s                  # => "$1$...$..."
+  #
+  #   apr = Passlib::MD5Crypt.create("hunter2", variant: :apr)
+  #   apr.to_s                   # => "$apr1$...$..."
+  #
+  # @!method self.create(secret, **options)
+  #   Creates a new MD5-crypt hash.
+  #   @param secret [String] the plaintext password
+  #   @option options [Symbol] :variant selects the MCF identifier: +:standard+
+  #     (default, produces +$1$+) or +:apr+ (produces +$apr1$+)
+  #   @option options [String] :salt custom salt string, 0-8 characters from
+  #     +./0-9A-Za-z+ (default: 8 random characters)
+  #   @return [MD5Crypt]
+  class MD5Crypt < Password
+    register :md5_crypt, mcf: %w[1 apr1]
+    options :variant, :salt
+
+    HASH_CHARS  = "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+    MAX_SALT_LEN = 8
+    ROUNDS       = 1000
+
+    MAGIC = { standard: "$1$", apr: "$apr1$" }.freeze
+
+    # Byte-index groups for encoding the 16-byte MD5 digest into 22 characters.
+    # The ordering matches the original FreeBSD md5crypt implementation by
+    # Poul-Henning Kamp. The final group encodes only one byte as 2 characters.
+    ENCODE_OFFSETS = [
+      [0,   6,  12, 4], [1,  7, 13, 4], [2, 8, 14, 4],
+      [3,   9,  15, 4], [4, 10,  5, 4], [nil, nil, 11, 2],
+    ].freeze
+
+    LOAD_PATTERN = %r{\A(\$1\$|\$apr1\$)([./0-9A-Za-z]{0,8})\$([./0-9A-Za-z]{22})\z}
+
+    private_constant :HASH_CHARS, :MAX_SALT_LEN, :ROUNDS, :MAGIC,
+                     :ENCODE_OFFSETS, :LOAD_PATTERN
+
+    # @param secret [String] the plaintext password to re-hash
+    # @return [MD5Crypt] a new instance hashed with the same salt and variant
+    def create_comparable(secret)
+      self.class.create(secret, salt: @salt, variant: @variant)
+    end
+
+    # MD5-crypt uses a fixed round count of 1000, so upgrade? is always false.
+    # @return [Boolean] always +false+
+    def upgrade?
+      false
+    end
+
+    private
+
+    def create(secret)
+      @variant = config.variant || :standard
+      @magic   = MAGIC.fetch(@variant) { raise ArgumentError, "unknown md5_crypt variant: #{@variant.inspect}" }
+      @salt    = (config.salt || random_salt)[0, MAX_SALT_LEN]
+      "#{@magic}#{@salt}$#{md5_digest(secret)}"
+    end
+
+    def load(string)
+      m = LOAD_PATTERN.match(string) or raise ArgumentError, "invalid md5_crypt hash: #{string.inspect}"
+      @magic   = m[1]
+      @variant = MAGIC.key(@magic)
+      @salt    = m[2]
+      string
+    end
+
+    def md5_digest(secret)
+      pw  = secret.encode("UTF-8").b
+      s   = @salt.b
+      mag = @magic.b
+
+      # Digest B = MD5(password + salt + password)
+      digest_b = OpenSSL::Digest::MD5.digest(pw + s + pw)
+
+      # Digest A = MD5(password + magic + salt + tiled_digest_b + bit_select)
+      ctx_a = OpenSSL::Digest::MD5.new
+      ctx_a.update(pw)
+      ctx_a.update(mag)
+      ctx_a.update(s)
+      plen = pw.bytesize
+      ctx_a.update(digest_b * (plen / 16)) if plen >= 16
+      ctx_a.update(digest_b[0, plen % 16]) if (plen % 16) > 0
+      len = plen
+      while len > 0
+        ctx_a.update(len.odd? ? "\x00" : pw[0])
+        len >>= 1
+      end
+      digest_a = ctx_a.digest
+
+      # Main loop: 1000 rounds mixing the current digest with password and salt
+      c = digest_a
+      ROUNDS.times do |i|
+        ctx_c = OpenSSL::Digest::MD5.new
+        ctx_c.update(i.odd? ? pw : c)
+        ctx_c.update(s)  unless (i % 3).zero?
+        ctx_c.update(pw) unless (i % 7).zero?
+        ctx_c.update(i.odd? ? c : pw)
+        c = ctx_c.digest
+      end
+
+      encode(c)
+    end
+
+    # Encodes the 16-byte MD5 digest into 22 characters using the FreeBSD
+    # md5crypt byte ordering and the crypt64 alphabet.
+    def encode(digest)
+      b = digest.bytes
+      ENCODE_OFFSETS.map { |w2, w1, w0, n|
+        v = ((w2 ? b[w2] : 0) << 16) | ((w1 ? b[w1] : 0) << 8) | b[w0]
+        n.times.map { c = HASH_CHARS[v & 0x3f]; v >>= 6; c }.join
+      }.join
+    end
+
+    def random_salt
+      Internal.random_bytes(6).bytes.map { HASH_CHARS[it & 63] }.join
+    end
+  end
+end

data/lib/passlib/password.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Passlib
+  # Abstract base class for all password hash implementations.
+  #
+  # Concrete subclasses (e.g. {BCrypt}, {PBKDF2}, {SHA2Crypt}) each implement a
+  # specific algorithm. The public interface is identical across all of them:
+  # use {.load} to parse a stored hash, {.create} to generate a new one, and
+  # {#verify} to verify a plaintext secret.
+  #
+  # Instances are immutable value objects. The underlying hash string is
+  # accessible via {#to_s}/{#to_str} and is always frozen.
+  #
+  # @abstract Subclass and implement the private +#create+ method (and optionally
+  #   +#load+ and/or +#verify+) to add a new algorithm.
+  #
+  # @example Parsing an existing hash
+  #   hash = Passlib::BCrypt.load("$2a$12$...")
+  #   hash.verify("hunter2")  # => true
+  #
+  # @example Creating a new hash
+  #   hash = Passlib::BCrypt.create("hunter2", cost: 10)
+  #   hash.to_s  # => "$2a$10$..."
+  class Password
+    extend Internal::DSL
+    @configuration_class = Configuration::Passlib
+
+    # Parses a stored hash string and returns a {Password} instance.
+    #
+    # When called on {Password} directly (rather than a concrete subclass), the
+    # algorithm is auto-detected from the hash format.  When called on a
+    # subclass, the string must be a valid hash for that algorithm.
+    #
+    # @param string [String] the stored password hash string
+    # @param config [Configuration, Hash, nil] optional configuration overrides
+    # @return [Password] a {Password} instance for the detected algorithm
+    # @raise [ArgumentError] if +string+ does not match any known format
+    #   (only when called on {Password} directly)
+    # @raise [Passlib::UnknownHashFormat] if +string+ is not valid for the
+    #   target algorithm (when called on a concrete subclass)
+    def self.load(string, config = nil, **)
+      return new(config(config, **), :load, string) if self != Password
+      case string
+      when /\A\$([\w-]+)/            then klass = Internal::Register::MFC_IDS[$1] || Internal::Register::MFC_IDS[$1[/\A\w+/]]
+      when /\A{([\w-]+)(?:,[^}]*)?}/ then klass = Internal::Register::LDAP_IDS[$1.upcase]
+      else
+        classes = Set.new
+        Internal::Register::PATTERNS.each do |pattern, candidate|
+          classes << candidate if pattern === string
+        end
+        klass = classes.first if classes.size == 1
+      end
+      return klass.load(string, config, **) if klass
+      raise ArgumentError, "unknown password hash format: #{string.inspect}"
+    end
+
+    # Creates a new password hash for the given secret.
+    #
+    # When called on a concrete subclass the algorithm is fixed.  When called
+    # on {Password} directly, the algorithm is selected from the configuration:
+    # set +preferred_scheme+ (a single identifier) or +preferred_schemes+ (an
+    # ordered list) in the supplied {Configuration::Passlib} and the first
+    # available algorithm in the list is used.  Raises {UnsupportedAlgorithm}
+    # when no usable scheme can be found.
+    #
+    # @param secret [String] the plaintext password to hash
+    # @param config [Configuration, Hash, nil] optional configuration overrides
+    # @param options [Hash] algorithm-specific keyword options (merged into +config+)
+    # @return [Password] a new {Password} instance wrapping the generated hash
+    # @raise [UnsupportedAlgorithm] if called on {Password} directly and no
+    #   preferred scheme is configured or available
+    def self.create(secret, config = nil, **)
+      config = config(config, **)
+      return new(config, :create, secret) if self != Password
+      scheme = config.preferred_scheme
+      return ::Passlib[scheme].create(secret, config) if scheme
+      raise UnsupportedAlgorithm, "no preferred schemes configured" if config.preferred_schemes.empty?
+      raise UnsupportedAlgorithm, "no available preferred schemes: #{config.preferred_schemes.join(", ")}"
+    end
+
+    # Returns whether this algorithm's dependency gem is installed and available.
+    # @return [Boolean]
+    def self.available? = true
+
+    private_class_method :new, :method_added
+
+    # The configuration used when this instance was created or loaded.
+    # @return [Configuration]
+    attr_reader :config
+    alias configuration config
+
+    # The frozen hash string, e.g. +"$2a$12$..."+ or +"{SSHA}..."+ .
+    # @return [String]
+    attr_reader :string
+    alias to_str string
+    alias to_s   string
+
+    # @api private
+    def initialize(config, method, ...)
+      super()
+      @config   = config
+      result    = send(method, ...)
+      @string ||= result.to_str
+      @string   = @string.frozen? ? @string : @string.dup.freeze
+    end
+
+    # @!method create_comparable(secret)
+    #   Re-hashes +secret+ using the same parameters (salt, rounds, etc.).
+    #
+    #   Not all subclasses define it, use +respond_to?(:create_comparable)+ to check.
+    #
+    #   @abstract
+    #   @param secret [String] the plaintext password to re-hash
+    #   @return [Password] a new instance hashed with the same parameters
+
+    # Verifies that +secret+ matches this password hash.
+    #
+    # Uses constant-time comparison via {Passlib.secure_compare} to prevent
+    # timing attacks.
+    #
+    # @param secret [String] the plaintext password to verify
+    # @return [Boolean] +true+ if the secret matches, +false+ otherwise
+    def verify(secret)
+      Passlib.secure_compare(self, create_comparable(secret))
+    rescue NameError => error
+      raise error unless error.name == :create_comparable
+      raise NotImplementedError, "subclass must implement #verify or #create_comparable"
+    end
+
+    # @!parse alias match? verify
+    def match?(secret) = verify(secret)
+    alias valid? match?
+    alias valid_secret? match?
+    alias valid_password? match?
+    alias === match?
+
+    # Returns a human-readable representation including the class name and hash string.
+    # @return [String]
+    # @api private
+    def inspect = "#<#{self.class.name} #{string.inspect}>"
+
+    # Pretty-print support for +pp+.
+    # @param pp [PP] the pretty-printer instance
+    # @return [void]
+    # @api private
+    def pretty_print(pp)
+      pp.object_group(self) do
+        pp.breakable
+        pp.pp string
+      end
+    end
+
+    # Returns whether this hash should be re-hashed with the current configuration.
+    #
+    # Called by {Passlib::Configuration::Context#upgrade?} after confirming the
+    # hash already uses the preferred algorithm.  Returns +true+ if any
+    # parameter (cost, rounds, etc.) does not exactly match the active
+    # configuration, including when stored costs are higher than configured
+    # (allowing a downgrade when parameters were set too high).
+    #
+    # @return [Boolean]
+    def upgrade? = raise NotImplementedError, "subclass must implement #upgrade?"
+
+    private
+
+    def load(string) = string
+    def create(string) = raise NotImplementedError, "subclass must override #create"
+  end
+end

data/lib/passlib/pbkdf2.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Passlib
+  # Handles PBKDF2 password hashing via OpenSSL, in Passlib's MCF format.
+  #
+  # Five digest variants are available: SHA-1, SHA-256, SHA-512, SHA3-256, and
+  # SHA3-512. The SHA3 variants are only usable when the OpenSSL build supports
+  # them; the default is SHA3-512 when available, falling back to SHA-512.
+  #
+  # Three hash formats are accepted on load, all normalized to MCF:
+  # - Passlib MCF: +$pbkdf2-sha256$rounds$salt$dk+
+  # - LDAP-style: +{PBKDF2-SHA256}rounds$salt$dk+
+  # - Cryptacular (+cta_pbkdf2_sha1+): +$p5k2$rounds_hex$salt_b64url$dk_b64url+
+  #
+  # New hashes are always produced in MCF.
+  #
+  # @example
+  #   hash = Passlib::PBKDF2.create("hunter2", variant: "pbkdf2-sha256", rounds: 29_000)
+  #   hash.verify("hunter2")  # => true
+  #   hash.to_s               # => "$pbkdf2-sha256$29000$...$..."
+  #
+  # @example Loading an LDAP hash (normalized to MCF)
+  #   hash = Passlib::PBKDF2.load("{PBKDF2-SHA256}29000$...$...")
+  #   hash.to_s               # => "$pbkdf2-sha256$29000$...$..."
+  #
+  # @example Loading a Cryptacular cta_pbkdf2_sha1 hash (normalized to MCF)
+  #   hash = Passlib::PBKDF2.load("$p5k2$2710$...$...")
+  #   hash.to_s               # => "$pbkdf2$10000$...$..."
+  #
+  # @!method self.create(secret, **options)
+  #   Creates a new PBKDF2 hash.
+  #   @param secret [String] the plaintext password
+  #   @option options [String, Symbol] :variant digest variant — one of +"pbkdf2"+ (SHA-1),
+  #     +"pbkdf2-sha256"+, +"pbkdf2-sha512"+, +"pbkdf2-sha3-256"+, +"pbkdf2-sha3-512"+;
+  #     case-insensitive, symbols accepted, underscores may be used instead of dashes
+  #     (default: +"pbkdf2-sha3-512"+ if SHA3 is available, otherwise +"pbkdf2-sha512"+)
+  #   @option options [Integer] :rounds  iteration count (default: variant-specific)
+  #   @option options [String]  :salt    raw binary salt (default: 16 random bytes)
+  #   @option options [Integer] :key_len derived key length in bytes (default: variant-specific)
+  #   @return [PBKDF2]
+  class PBKDF2 < Password
+    VARIANTS = {
+      "pbkdf2"          => { digest: "SHA1",     key_len: 20, default_rounds: 131_000 },
+      "pbkdf2-sha256"   => { digest: "SHA256",   key_len: 32, default_rounds:  29_000 },
+      "pbkdf2-sha512"   => { digest: "SHA512",   key_len: 64, default_rounds:  25_000 },
+      "pbkdf2-sha3-256" => { digest: "SHA3-256", key_len: 32, default_rounds:  29_000 },
+      "pbkdf2-sha3-512" => { digest: "SHA3-512", key_len: 64, default_rounds:  25_000 },
+    }.freeze
+
+    # Mapping from LDAP-style variant names to their MCF equivalents.
+    LDAP_VARIANTS = {
+      "PBKDF2"          => "pbkdf2",
+      "PBKDF2-SHA256"   => "pbkdf2-sha256",
+      "PBKDF2-SHA512"   => "pbkdf2-sha512",
+      "PBKDF2-SHA3-256" => "pbkdf2-sha3-256",
+      "PBKDF2-SHA3-512" => "pbkdf2-sha3-512",
+    }.freeze
+
+    # AB64 alphabet: A-Za-z0-9 plus '.' (replaces '+') and '/'
+    MCF_PATTERN  = /\A\$(pbkdf2(?:-sha3?-?\d+)?)\$(\d+)\$([A-Za-z0-9.\/]+)\$([A-Za-z0-9.\/]+)\z/
+    LDAP_PATTERN = /\A\{(PBKDF2[^}]*)\}(\d+)\$([A-Za-z0-9.\/]+)\$([A-Za-z0-9.\/]+)\z/i
+    # Cryptacular's PBKDF2-SHA1 format: $p5k2$<rounds_hex>$<salt_b64url>$<checksum_b64url>
+    CTA_PATTERN  = %r{\A\$p5k2\$([0-9a-f]+)\$([A-Za-z0-9_=-]+)\$([A-Za-z0-9_=-]+)\z}
+
+    DEFAULT = OpenSSL::Digest.digests.any? { it.casecmp?("SHA3-512") } ? "pbkdf2-sha3-512" : "pbkdf2-sha512"
+
+    private_constant :VARIANTS, :LDAP_VARIANTS, :MCF_PATTERN, :LDAP_PATTERN, :CTA_PATTERN, :DEFAULT
+
+    register mcf: %w[pbkdf2 p5k2]
+    options :variant, :rounds, :salt, :key_len
+
+    # Register LDAP variant names for auto-detection via Passlib.load
+    LDAP_VARIANTS.each_key { Internal::Register::LDAP_IDS[_1] = self }
+
+    # @param secret [String] the plaintext password to re-hash
+    # @return [PBKDF2] a new instance hashed with the same variant, rounds, salt, and key length
+    def create_comparable(secret)
+      self.class.create(secret, variant: @variant, rounds: @rounds, salt: @salt, key_len: @key_len)
+    end
+
+    def upgrade?
+      v = VARIANTS[@variant] or return false
+      @rounds != (config.rounds || v[:default_rounds])
+    end
+
+    private
+
+    def create(secret)
+      @variant ||= (config.variant || DEFAULT).to_s.downcase.tr("_", "-")
+      v          = VARIANTS[@variant] or raise ArgumentError, "unknown pbkdf2 variant: #{@variant.inspect}"
+      @rounds  ||= config.rounds  || v[:default_rounds]
+      @key_len ||= config.key_len || v[:key_len]
+      @salt    ||= config.salt    || Internal.random_bytes(16)
+      dk         = OpenSSL::PKCS5.pbkdf2_hmac(secret.to_s, @salt, @rounds, @key_len, v[:digest])
+      "$#{@variant}$#{@rounds}$#{Internal.encode_ab64(@salt)}$#{Internal.encode_ab64(dk)}"
+    end
+
+    def load(string)
+      case string
+      when MCF_PATTERN
+        m        = Regexp.last_match
+        @variant = m[1]
+        @rounds  = m[2].to_i
+        @salt    = Internal.decode_ab64(m[3])
+        @key_len = Internal.decode_ab64(m[4]).bytesize
+        string
+      when LDAP_PATTERN
+        m        = Regexp.last_match
+        ldap_var = m[1].upcase
+        @variant = LDAP_VARIANTS[ldap_var] or raise UnknownHashFormat, "unknown LDAP PBKDF2 scheme: #{ldap_var.inspect}"
+        @rounds  = m[2].to_i
+        @salt    = Internal.decode_ab64(m[3])
+        @key_len = Internal.decode_ab64(m[4]).bytesize
+        "$#{@variant}$#{@rounds}$#{m[3]}$#{m[4]}"
+      when CTA_PATTERN
+        m        = Regexp.last_match
+        @variant = "pbkdf2"
+        @rounds  = m[1].to_i(16)
+        @salt    = decode_url64(m[2])
+        @key_len = decode_url64(m[3]).bytesize
+        "$pbkdf2$#{@rounds}$#{Internal.encode_ab64(@salt)}$#{m[3].then { Internal.encode_ab64(decode_url64(_1)) }}"
+      else
+        raise UnknownHashFormat, "invalid pbkdf2 hash: #{string.inspect}"
+      end
+    end
+
+    def decode_url64(str)
+      s = str.tr("-_", "+/")
+      s += "=" * ((-s.length) % 4) unless s.end_with?("=")
+      s.unpack1("m")
+    end
+  end
+end