Module: RbNaCl::PasswordHash

Defined in:
lib/rbnacl/password_hash.rb,
lib/rbnacl/password_hash/argon2.rb,
lib/rbnacl/password_hash/scrypt.rb

Overview

Password hashing functions

These hash functions are designed specifically for the purposes of securely storing passwords in a way that they can be checked against a supplied password but an attacker who obtains a hash cannot easily reverse them back into the original password.

Unlike normal hash functions, which are intentionally designed to hash data as quickly as they can while remaining secure, password hashing functions are intentionally designed to be slow so they are hard for attackers to brute force.

All password hashing functions take a "salt" value which should be randomly generated on a per-password basis (using RbNaCl::Random, accept no substitutes)

All of them also take a CPU work factor, which increases the amount of computation needed to produce the digest.

Defined Under Namespace

Classes: Argon2, SCrypt

Class Method Summary collapse

Class Method Details

.argon2(password, salt, opslimit, memlimit, digest_size = 64) ⇒ String

argon2: state of the art in the design of memory-hard hashing functions.

Parameters:

  • password (String) —

    to be hashed

  • salt (String) —

    to make the digest unique

  • opslimit (Integer) —

    the CPU cost (3..10)

  • memlimit (Integer) —

    the memory cost, in bytes

  • digest_size (Integer) (defaults to: 64) —

    of the output

Returns:

  • (String) —

    The argon2i digest as raw bytes

Raises:

  • (CryptoError) —

    If calculating the digest fails for some reason.



50
51
52
 
# File 'lib/rbnacl/password_hash.rb', line 50

def self.argon2(password, salt, opslimit, memlimit, digest_size = 64)
  argon2_supported? && Argon2.new(opslimit, memlimit, digest_size).digest(password, salt)
end

.argon2_str(password, opslimit = :interactive, memlimit = :interactive) ⇒ String

argon2_str: crypt-style password digest

Parameters:

  • password (String) —

    to be hashed

  • opslimit (Integer) (defaults to: :interactive) —

    the CPU cost (3..10)

  • memlimit (Integer) (defaults to: :interactive) —

    the memory cost, in bytes

Returns:

  • (String) —

    The argon2i digest as crypt-style string

Raises:

  • (CryptoError) —

    If calculating the digest fails for some reason.



63
64
65
 
# File 'lib/rbnacl/password_hash.rb', line 63

def self.argon2_str(password, opslimit = :interactive, memlimit = :interactive)
  argon2_supported? && Argon2.new(opslimit, memlimit).digest_str(password)
end

.argon2_valid?(password, str_digest) ⇒ Boolean

argon2_valid?: verify crypt-style password digest

Parameters:

  • password (String) —

    to verify

  • str_digest (String) —

    to verify

Returns:

  • (Boolean) —

    true if digest was created using password



73
74
75
 
# File 'lib/rbnacl/password_hash.rb', line 73

def self.argon2_valid?(password, str_digest)
  argon2_supported? && Argon2.digest_str_verify(password, str_digest)
end

.scrypt(password, salt, opslimit, memlimit, digest_size = 64) ⇒ String

scrypt: the original sequential memory-hard password hashing function.

Parameters:

  • password (String) —

    to be hashed

  • salt (String) —

    to make the digest unique

  • opslimit (Integer) —

    the CPU cost (e.g. 2**20)

  • memlimit (Integer) —

    the memory cost (e.g. 2**24)

  • digest_size (Integer) (defaults to: 64) —

    of the output

Returns:

  • (String) —

    The scrypt digest as raw bytes

Raises:

  • (CryptoError) —

    If calculating the digest fails for some reason.



35
36
37
 
# File 'lib/rbnacl/password_hash.rb', line 35

def self.scrypt(password, salt, opslimit, memlimit, digest_size = 64)
  SCrypt.new(opslimit, memlimit, digest_size).digest(password, salt)
end