Crypt::KeyDerivation(3)

NAME
Crypt::KeyDerivation - PBKDF1, PBKDF2, HKDF, Bcrypt, Scrypt, Argon2 key derivation functions

SYNOPSIS
  use Crypt::KeyDerivation ':all';

  ### PBKDF1/2
  $derived_key1 = pbkdf1($password, $salt, $iteration_count, $hash_name, $len);
  $derived_key2 = pbkdf1_openssl($password, $salt, $iteration_count, $hash_name, $len);
  $derived_key3 = pbkdf2($password, $salt, $iteration_count, $hash_name, $len);

  ### HKDF & co.
  $derived_key4 = hkdf($keying_material, $salt, $hash_name, $len, $info);
  $prk  = hkdf_extract($keying_material, $salt, $hash_name);
  $okm1 = hkdf_expand($prk, $hash_name, $len, $info);

  ### bcrypt / scrypt / argon2
  $derived_key4 = bcrypt_pbkdf($password, $salt, $rounds, $hash_name, $len);
  $derived_key5 = scrypt_pbkdf($password, $salt, $N, $r, $p, $len);
  $derived_key6 = argon2_pbkdf($type, $password, $salt, $t_cost, $m_factor, $parallelism, $len, $secret, $ad);

DESCRIPTION
Provides an interface to key derivation functions:

•   PBKDF1 and PBKDF2 according to PKCS#5 v2.0 <https://tools.ietf.org/html/rfc2898>

•   HKDF (+ related) according to <https://tools.ietf.org/html/rfc5869>

•   Bcrypt-PBKDF as defined by the OpenBSD project

•   Scrypt according to <https://tools.ietf.org/html/rfc7914>

•   Argon2 according to <https://tools.ietf.org/html/rfc9106>

While primarily designed for key derivation, the functions PBKDF2, Bcrypt, Scrypt and Argon2 are also widely used for password hashing. In that use case the derived key serves as the stored password hash.

FUNCTIONS

  pbkdf1
BEWARE: if you are not sure, do not use "pbkdf1" but rather choose "pbkdf2".

  $derived_key = pbkdf1($password, $salt, $iteration_count, $hash_name, $len);
  #or
  $derived_key = pbkdf1($password, $salt, $iteration_count, $hash_name);
  #or
  $derived_key = pbkdf1($password, $salt, $iteration_count);
  #or
  $derived_key = pbkdf1($password, $salt);

  # $password ......... input keying material  (password)
  # $salt ............. salt/nonce (expected length: 8)
  # $iteration_count .. optional, DEFAULT: 5000
  # $hash_name ........ optional, DEFAULT: 'SHA256'
  # $len .............. optional, derived key len, DEFAULT: 32

  pbkdf1_openssl
Since: CryptX-0.088

OpenSSL-compatible variant of PBKDF1 (implements "EVP_BytesToKey"). Unlike strict "pbkdf1", the output length is not limited to the hash size -- it can be arbitrarily long by chaining hash blocks. OpenSSL defaults: "MD5" hash, "iteration_count=1".

  $derived_key = pbkdf1_openssl($password, $salt, $iteration_count, $hash_name, $len);
  #or
  $derived_key = pbkdf1_openssl($password, $salt, $iteration_count, $hash_name);
  #or
  $derived_key = pbkdf1_openssl($password, $salt, $iteration_count);
  #or
  $derived_key = pbkdf1_openssl($password, $salt);

  # $password ......... input keying material (password)
  # $salt ............. salt/nonce (expected length: 8)
  # $iteration_count .. optional, DEFAULT: 5000
  # $hash_name ........ optional, DEFAULT: 'SHA256'
  # $len .............. optional, derived key len, DEFAULT: 32

  pbkdf2
  $derived_key = pbkdf2($password, $salt, $iteration_count, $hash_name, $len);
  #or
  $derived_key = pbkdf2($password, $salt, $iteration_count, $hash_name);
  #or
  $derived_key = pbkdf2($password, $salt, $iteration_count);
  #or
  $derived_key = pbkdf2($password, $salt);

  # $password ......... input keying material (password)
  # $salt ............. salt/nonce
  # $iteration_count .. optional, DEFAULT: 5000
  # $hash_name ........ optional, DEFAULT: 'SHA256'
  # $len .............. optional, derived key len, DEFAULT: 32

  hkdf
  $okm2 = hkdf($password, $salt, $hash_name, $len, $info);
  #or
  $okm2 = hkdf($password, $salt, $hash_name, $len);
  #or
  $okm2 = hkdf($password, $salt, $hash_name);
  #or
  $okm2 = hkdf($password, $salt);

  # $password ... input keying material (password)
  # $salt ....... salt/nonce, if undef defaults to HashLen zero octets
  # $hash_name .. optional, DEFAULT: 'SHA256'
  # $len ........ optional, derived key len, DEFAULT: 32
  # $info ....... optional context and application specific information, DEFAULT: ''

  hkdf_extract
  $prk  = hkdf_extract($password, $salt, $hash_name);
  #or
  $prk  = hkdf_extract($password, $salt, $hash_name);

  # $password ... input keying material (password)
  # $salt ....... salt/nonce, if undef defaults to HashLen zero octets
  # $hash_name .. optional, DEFAULT: 'SHA256'

  hkdf_expand
  $okm = hkdf_expand($pseudokey, $hash_name, $len, $info);
  #or
  $okm = hkdf_expand($pseudokey, $hash_name, $len);
  #or
  $okm = hkdf_expand($pseudokey, $hash_name);
  #or
  $okm = hkdf_expand($pseudokey);

  # $pseudokey .. input keying material
  # $hash_name .. optional, DEFAULT: 'SHA256'
  # $len ........ optional, derived key len, DEFAULT: 32
  # $info ....... optional context and application specific information, DEFAULT: ''

  bcrypt_pbkdf
bcrypt-based key derivation as defined by the OpenBSD project.

Since: CryptX-0.088

  $derived_key = bcrypt_pbkdf($password, $salt, $rounds, $hash_name, $len);
  #or
  $derived_key = bcrypt_pbkdf($password, $salt, $rounds, $hash_name);
  #or
  $derived_key = bcrypt_pbkdf($password, $salt, $rounds);
  #or
  $derived_key = bcrypt_pbkdf($password, $salt);

  # $password ... input keying material (password)
  # $salt ....... salt/nonce
  # $rounds ..... optional, number of rounds, DEFAULT: 16
  # $hash_name .. optional, DEFAULT: 'SHA512'
  # $len ........ optional, derived key len, DEFAULT: 32

  scrypt_pbkdf
scrypt key derivation according to <https://tools.ietf.org/html/rfc7914>.

Since: CryptX-0.088

  $derived_key = scrypt_pbkdf($password, $salt, $N, $r, $p, $len);
  #or
  $derived_key = scrypt_pbkdf($password, $salt, $N, $r, $p);
  #or
  $derived_key = scrypt_pbkdf($password, $salt, $N);
  #or
  $derived_key = scrypt_pbkdf($password, $salt);

  # $password ... input keying material (password)
  # $salt ....... salt/nonce
  # $N .......... optional, CPU/memory cost parameter (power of 2), DEFAULT: 1024
  # $r .......... optional, block size, DEFAULT: 8
  # $p .......... optional, parallelization parameter, DEFAULT: 1
  # $len ........ optional, derived key len, DEFAULT: 32

  argon2_pbkdf
Argon2 key derivation according to <https://tools.ietf.org/html/rfc9106>.

Since: CryptX-0.088

  $derived_key = argon2_pbkdf($type, $password, $salt, $t_cost, $m_factor, $parallelism, $len, $secret, $ad);
  #or
  $derived_key = argon2_pbkdf($type, $password, $salt, $t_cost, $m_factor, $parallelism, $len);
  #or
  $derived_key = argon2_pbkdf($type, $password, $salt, $t_cost, $m_factor, $parallelism);
  #or
  $derived_key = argon2_pbkdf($type, $password, $salt);

  # $type        ... one of 'argon2d', 'argon2i', 'argon2id'
  # $password    ... input keying material (password)
  # $salt        ... salt/nonce
  # $t_cost      ... optional, time cost (number of iterations), DEFAULT: 3
  # $m_factor    ... optional, memory cost in kibibytes, DEFAULT: 65536
  # $parallelism ... optional, degree of parallelism, DEFAULT: 1
  # $len         ... optional, derived key len, DEFAULT: 32
  # $secret      ... optional, secret value, DEFAULT: ''
  # $ad          ... optional, associated data, DEFAULT: ''