6 Key Derivation and Password Hashing🔗ℹ

A key derivation function can be used to derive keys from secret material that is not directly suitable for use as a key, such as a passphrase or the result of a key agreement algorithm. Differnt KDFs have different additional parameters such as work factors and context information fields.

KDFs with adjustable work factors are also used to store passwords [HtSSaP, DUB]. A KDF is preferable to a simple digest function (even with a salt) because the work factor can be chosen to make exhaustively searching the space of likely passwords (typically short and composed of alpha-numeric characters) costly.

There are two groups of KDF specifiers. The following KDFs have work factors and are suitable for producing keys from passwords and storing passwords:

• (list 'pbkdf2 'hmac digest-spec) — the PBKDF2 function from PKCS#5 [PKCS5] using HMAC of digest-spec (see digest-spec?).

• 'scrypt — scrypt, with work factors for both time and memory [scrypt]

• 'argon2d, 'argon2i, 'argon2id — variants of Argon2, designed primarily for password hashing [Argon2, PHC]

The following KDFs are suitable for producing keys from the results of key-agreement algorithms. They are not suitable for storing passwords.

• (list 'hkdf digest-spec) — the HKDF extract-then-expand function [HKDF]

• (list 'concat digest-spec) — the Concatentation (also called One-Step) KDF from NIST SP 800-56C [SP800-56C] using a plain digest

• (list 'concat 'hmac digest-spec) — the Concatentation KDF [SP800-56C] using HMAC-digest-spec

• (list 'sp800-108-counter 'hmac digest-spec), (list 'sp800-108-feedback 'hmac digest-spec), and (list 'sp800-108-double-pipeline 'hmac digest-spec) — KDF constructions from NIST SP 800-108 [SP800-108]; this library only supports 32-bit counters and the standard ordering of components

• (list 'ans-x9.63 digest-spec) — similar to the concatenation KDF but with a different order of components, defined by ANSI [X963]

Changed in version 1.3 of package crypto-lib: Added support for 'hkdf, 'concat, 'sp800-108-*, and 'ans-x9.63 algorithms.

The salt must be a bytestring (bytes?) except in the following cases: if the KDF is 'ans-x9.63, 'concat with a digest, 'sp800-108-counter, or 'sp800-108-double-pipeline, then salt must be #f; if the KDF is 'hkdf or 'concat with HMAC, then salt may be either #f or a bytestring.

The following parameters are recognized for (list 'pbkdf2 'hmac digest):

• (list 'iterations iterations) — number of iterations

• (list 'key-size key-size) — the size of the output

In 2000 PKCS#5 [PKCS5] recommended a minimum of 1000 iterations; the iteration count should be exponentially larger today.

The following parameters are recognized for 'scrypt:

• (list 'N N) — the CPU/memory cost

• (list 'p p) — the parallelization factor

• (list 'r r) — the block size

• (list 'key-size key-size) — the size of the output

In 2009 the original scrypt paper [scrypt] used parameters such as 214 to 220 for N, 1 for p, and 8 for r.

The following parameters are recognized for 'argon2d, 'argon2i, and 'argon2id:

• (list 't t) — the time cost

• (list 'm m) — the memory cost (in kb)

• (list 'p p) — the parallelism

• (list 'key-size key-size) – the size of the output

The following parameters are recognized for the 'hkdf, 'concat, 'sp800-108-*, and 'asn-x9.63 families of KDFs:

• (list 'info info-bytes) — additional contextual information; see [HKDF, SP800-56A, SP800-108] for recommendations regarding the contents and format of this field

• (list 'key-size key-size) — the size of the output

The config parameters are nearly the same as for kdf, with the following exceptions:

• The 'scrypt algorithm requires a parameter 'ln specifying the log (base 2) of the iteration count, instead of the 'N parameter expected by the kdf function.

• The 'key-size parameter is not allowed. This library always generates password hashes with 32 bytes of raw output (before encoding).

Added in version 1.2 of package crypto-lib.

If k is a KDF implementation (kdf-impl?), pwh must have been generated with the same KDF algorithm (but not necessarily the same implementation); otherwise an exception is raised. If k is #f, then the KDF algorithm is extracted from pwh and the (crypto-factories) list is searched for an implementation; if no implementation is found an exception is raised.

Added in version 1.2 of package crypto-lib.