Module: Passlib

Extended by:
Passlib, Configuration::Context
Included in:
Passlib
Defined in:
lib/passlib.rb,
lib/passlib/argon2.rb,
lib/passlib/bcrypt.rb,
lib/passlib/pbkdf2.rb,
lib/passlib/phpass.rb,
lib/passlib/scrypt.rb,
lib/passlib/balloon.rb,
lib/passlib/context.rb,
lib/passlib/version.rb,
lib/passlib/internal.rb,
lib/passlib/password.rb,
lib/passlib/yescrypt.rb,
lib/passlib/md5_crypt.rb,
lib/passlib/sha1_crypt.rb,
lib/passlib/sha2_crypt.rb,
lib/passlib/ldap_digest.rb,
lib/passlib/bcrypt_sha256.rb,
lib/passlib/configuration.rb

Overview

Top-level namespace for the Passlib gem.

Passlib is an algorithm-agnostic password hashing library. It provides a unified interface for creating and verifying password hashes across many supported algorithms, and auto-detects the algorithm from any stored hash string.

Examples:

Verifying a stored hash

Passlib.verify("hunter2", "$2a$12$...")  # => true

Loading an existing hash and verifying

hash = Passlib.load("$2a$12$...")
hash.verify("hunter2")  # => true

Creating a hash with a specific algorithm

Passlib::BCrypt.create("hunter2", cost: 12).to_s  # => "$2a$12$..."

See Also:

Defined Under Namespace

Classes: Argon2, BCrypt, Balloon, BcryptSHA256, Configuration, Context, LdapDigest, MD5Crypt, PBKDF2, PHPass, Password, SCrypt, SHA1Crypt, SHA2Crypt, Yescrypt

Constant Summary collapse

VERSION =

The current version of the Passlib gem.

Returns:

  • (String) 
"0.1.0"

Instance Method Summary collapse

Methods included from Configuration::Context

configuration, configuration=, configure, create, load, upgrade, upgrade?, verify

Instance Method Details

#[](key) ⇒ Class<Password>?

Looks up a password algorithm class by identifier.

Parameters:

  • key (Symbol, String, Class) —

    algorithm identifier (e.g. :bcrypt, “bcrypt”) or a Password subclass (returned as-is)

Returns:

  • (Class<Password>, nil) —

    the corresponding Password subclass, or nil if the identifier is not recognized



76
77
78
79
 
# File 'lib/passlib.rb', line 76

def [](key)
  return key if key.is_a?(Class) and key <= Password
  Internal::Register::IDENTIFIERS[key.to_sym]
end

#available?(algorithm) ⇒ Boolean?

Returns whether the given algorithm is available (i.e. its dependency gem is installed).

Parameters:

  • algorithm (Symbol, String, Class) —

    algorithm identifier or Password subclass

Returns:

  • (Boolean, nil) —

    true if available, false if the dependency is missing, nil if the algorithm identifier is not recognized at all



86
 
# File 'lib/passlib.rb', line 86

def available?(algorithm) = self[algorithm]&.available?

#secure_compare(trusted, untrusted) ⇒ Boolean

Performs a constant-time string comparison to prevent timing attacks.

Returns false immediately—without leaking length information through timing—when either argument does not respond to #to_str. Returns false when the byte lengths differ, also in constant time.

Parameters:

  • trusted (#to_str) —

    the expected (stored) value

  • untrusted (#to_str) —

    the candidate value to compare against trusted

Returns:

  • (Boolean) —

    true if both strings are byte-for-byte identical



60
61
62
63
64
65
66
67
68
 
# File 'lib/passlib.rb', line 60

def secure_compare(trusted, untrusted)
  return false unless trusted.respond_to?   :to_str and trusted = trusted.to_str.b
  return false unless untrusted.respond_to? :to_str and untrusted = untrusted.to_str.b

  # avoid ability for attacker to guess length of string by timing attack
  comparable = trusted[0, untrusted.bytesize].ljust(untrusted.bytesize, "\0".b)
  result     = OpenSSL.fixed_length_secure_compare(comparable, untrusted)
  trusted.bytesize == untrusted.bytesize and result
end