Class: CryptCheckpass

Inherits:
Object
  • Object
show all
Defined in:
lib/crypt_checkpass/api.rb

Overview

Mother of all KDF classes.

Subclasses of this are expected to implement the following 4 class methods:

  • subclass.provide?(id)
  • subclass.newhash(pass, id: id, ...)
  • subclass.understand?(hash)
  • subclass.checkpass?(pass, hash)

If a subclass's provide? returns true for an id, then that class is responsible for generating new hash of that id. Likewise if understand? returns true for a hash, that should be able to checkpass.

Caveats:

  • You don't have to provide all of those methods. It is completely reasonable to have a hash that is unable to generate new one, but still able to check existing ones.

Direct Known Subclasses

Argon2, Bcrypt, PBKDF2, SHA2, Scrypt

Defined Under Namespace

Modules: PHCStringFormat Classes: Argon2, Bcrypt, PBKDF2, SHA2, Scrypt

API entry points collapse

Inteacts with subclasses collapse

Class Method Details

.checkpass?(pass, hash) ⇒ true, false

Checks if the given password matches the hash.

Parameters:

  • pass (String) —

    a password to test.

  • hash (String) —

    a good hash digest string.

Returns:

  • (true) —

    they are identical.

  • (false) —

    they are distinct.

Raises:

  • (NotImplementedError) —

    don't know how to parse hash.



107
108
109
 
# File 'lib/crypt_checkpass/api.rb', line 107

def checkpass? pass, hash
  return false # default false
end

.crypt_checkpass?(pass, hash) ⇒ true, false

Parses what the given hash is, apply the same hasing against pass, then compares the hashed pass and the given hash.

Parameters:

  • pass (String) —

    password string.

  • hash (String) —

    hashed string.

Returns:

  • (true) —

    they are identical.

  • (false) —

    they are distinct.

Raises:

  • (NotImplementedError) —

    don't know how to parse hash.



54
55
56
57
 
# File 'lib/crypt_checkpass/api.rb', line 54

def crypt_checkpass? pass, hash
  kdf = find_kdf_by_string hash
  return kdf.checkpass? pass, hash
end

.crypt_newhash(password, perf) ⇒ String .crypt_newhash(password, id: , **kwargs) ⇒ String

Generates new password hashes. The provided password is randomly salted, then hashed using the parameter.

Overloads:

  • .crypt_newhash(password, perf) ⇒ String
    Note:

    This usage is for OpenBSD fans.

    The pref argument identifies the preferred hashing algorithm and parameters. Possible values are:

    • "bcrypt,<rounds>"
    • "blowfish,<rounds>"

    where "rounds" can be a number between 4 and 31, or "a" for default.

    Parameters:

    • password (String) —

      bare, unhashed binary password.

    • pref (String) —

      algorithm preference specifier.

    Returns:

    • (String) —

      hashed digest string of password.

    Raises:

    • (NotImplementedError) —

      pref not understandable.

    See Also:

  • .crypt_newhash(password, id: , **kwargs) ⇒ String

    At least :id argument must be provided this case, which is the name of key deliveration function (the ID that the PHC string format says).

    Parameters:

    • password (String) —

      bare, unhashed binary password.

    • id (String) (defaults to: ) —

      name of the function.

    • kwargs (Symbol=>String, Integer) —

      passed to the KDF.

    Returns:

    • (String) —

      hashed digest string of password.

    Raises:

    • (NotImplementedError) —

      unknown KDF is specified.

Raises:

  • (ArgumentError) 


60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/crypt_checkpass/api.rb', line 60

def crypt_newhash password, pref = nil, id: nil, **kwargs
  raise ArgumentError, <<-"end".strip if pref && id
    wrong number of arguments (given 2, expected 1)
  end
  raise ArgumentError, <<-"end".strip, kwargs.keys if pref &&! kwargs.empty?
    unknown key: %p
  end

  if pref then
    require_relative 'bcrypt'
    return CryptCheckpass::Bcrypt.new_with_openbsd_pref password, pref
  else
    kdf = find_kdf_by_id id
    return kdf.newhash password, id: id, **kwargs
  end
end

.newhash ⇒ String

Note:

There is no way to specify salt. That's a bad idea.

Generate a new password hash string.

Returns:

  • (String) —

    hashed digest string of password.



115
116
117
 
# File 'lib/crypt_checkpass/api.rb', line 115

def newhash *;
  raise 'NOTREACHED'
end

.provide?(id) ⇒ true, false

Checks if the given ID can be handled by this class. A class is free to handle several IDs, like 'argon2i', 'argon2d', ...

Parameters:

  • id (String) —

    hash function ID.

Returns:

  • (true) —

    it does.

  • (false) —

    it desn't.



87
88
89
 
# File 'lib/crypt_checkpass/api.rb', line 87

def provide? id
  return false # default false
end

.understand?(str) ⇒ true, false

Checks if the given hash string can be handled by this class.

Parameters:

  • str (String) —

    a good hashed string.

Returns:

  • (true) —

    it does.

  • (false) —

    it desn't.



96
97
98
 
# File 'lib/crypt_checkpass/api.rb', line 96

def understand? str
  return false # default false
end