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: ''

cpanm CryptX

perl -MCPAN -e shell
install CryptX