Module: Passlib::Configuration::Context

Included in:
Passlib, Passlib::Context
Defined in:
lib/passlib/configuration/context.rb

Overview

Mixin that provides configuration, hash-loading, and hash-creation helpers.

Extended into the Passlib module (so all methods are available as Passlib.load, Passlib.create, etc.)

Instance Method Summary collapse

Instance Method Details

#configuration ⇒ Configuration Also known as: config

Returns the active Passlib::Configuration for this object.

The first call initializes the configuration, inheriting from Passlib.configuration unless this object is the Passlib module.

Returns:



14
 
# File 'lib/passlib/configuration/context.rb', line 14

def configuration = @configuration ||= Passlib::Configuration.new(base_config)

#configuration=(value) ⇒ void Also known as: config=

This method returns an undefined value.

Replaces the current configuration options.

Parameters:

  • value (Configuration, Hash) —

    new configuration or option overrides

See Also:



21
22
23
 
# File 'lib/passlib/configuration/context.rb', line 21

def configuration=(value)
  configuration.set(value)
end

#configure {|config| ... } ⇒ void Also known as: setup

This method returns an undefined value.

Yields the current configuration to a block for modification.

Yield Parameters:



31
 
# File 'lib/passlib/configuration/context.rb', line 31

def configure = yield(config)

#create(secret) ⇒ Password

Creates a new password hash for the given secret using the current configuration.

Delegates to Password.create with the current configuration applied. A preferred algorithm must be configured or a concrete subclass used.

Parameters:

  • secret (String) —

    the plaintext password to hash

Returns:



51
 
# File 'lib/passlib/configuration/context.rb', line 51

def create(secret, **) = Passlib::Password.create(secret, config, **)

#load(payload) ⇒ Password

Parses a stored hash string and returns a Password instance.

Delegates to Password.load with the current configuration applied.

Parameters:

  • payload (String) —

    the stored password hash string

Returns:

Raises:

  • (ArgumentError) —

    if the hash format is not recognized

  • (Passlib::UnknownHashFormat) —

    if the format is recognized but invalid



42
 
# File 'lib/passlib/configuration/context.rb', line 42

def load(payload, **)  = Passlib::Password.load(payload,  config, **)

#upgrade(secret, hash, verify: true) ⇒ Password?

Re-hashes a password if the stored hash is outdated.

First verifies secret against hash (unless verify: false). Returns nil if verification fails or no upgrade is needed. Otherwise creates and returns a new hash using the current configuration (algorithm and cost parameters).

The argument order may be swapped: if the first argument is a Password instance and the second is a String, they are treated as (hash, secret).

Parameters:

  • secret (String, Password) —

    the plaintext password (or hash if swapped)

  • hash (String, Password) —

    the stored password hash (or secret if swapped)

  • verify (Boolean) (defaults to: true) —

    when false, skip password verification before upgrading (default: true)

Returns:



110
111
112
113
114
115
116
 
# File 'lib/passlib/configuration/context.rb', line 110

def upgrade(secret, hash, verify: true)
  secret, hash = hash, secret if secret.is_a? Passlib::Password and not hash.is_a? Passlib::Password
  hash = load(hash) unless hash.is_a? Passlib::Password
  return if verify and not verify(secret, hash)
  return unless upgrade?(hash)
  create(secret)
end

#upgrade?(hash) ⇒ Boolean

Returns whether a stored hash should be re-hashed.

Returns false immediately when no preferred scheme is configured. Returns true when the hash uses a different algorithm than the preferred scheme. When the algorithm already matches, delegates to Password#upgrade? to check whether the cost parameters are weaker than those in the current configuration.

Parameters:

  • hash (String, Password) —

    the stored password hash to evaluate

Returns:

  • (Boolean) —

    true if the hash should be upgraded, false otherwise



87
88
89
90
91
92
 
# File 'lib/passlib/configuration/context.rb', line 87

def upgrade?(hash)
  return false unless target = config.preferred_scheme
  hash = load(hash) unless hash.is_a? Passlib::Password
  return true unless hash.is_a? Passlib[target]
  hash.upgrade?
end

#verify(secret, hash) ⇒ Boolean Also known as: match?, valid_secret?, valid_password?

Verifies a plaintext secret against a stored password hash.

The argument order may be swapped: if the first argument is a Password instance and the second is a String, they are treated as (hash, secret).

Equivalent to Passlib.load(hash).verify(secret).

Parameters:

  • secret (String) —

    the plaintext password to verify

  • hash (String) —

    the stored password hash string

Returns:

  • (Boolean) —

    true if the secret matches the hash, false otherwise

Raises:

  • (ArgumentError) —

    if the hash format is not recognized

  • (Passlib::UnsupportedAlgorithm) —

    if the algorithm is unavailable

See Also:



67
68
69
70
71
 
# File 'lib/passlib/configuration/context.rb', line 67

def verify(secret, hash)
  secret, hash = hash, secret if secret.is_a? Passlib::Password and not hash.is_a? Passlib::Password
  hash = load(hash) unless hash.is_a? Passlib::Password
  hash.verify(secret)
end