nettle: Key derivation functions
1
1 6.6 Key derivation Functions
1 ============================
1
1 A “key derivation function” (KDF) is a function that from a given
1 symmetric key derives other symmetric keys. A sub-class of KDFs is the
1 “password-based key derivation functions” (PBKDFs), which take as input
1 a password or passphrase, and its purpose is typically to strengthen it
1 and protect against certain pre-computation attacks by using salting and
1 expensive computation.
1
1 6.6.1 HKDF: HMAC-based Extract-and-Expand
1 -----------------------------------------
1
1 HKDF is a key derivation function used as a building block of
1 higher-level protocols like TLS 1.3. It is a derivation function based
1 on HMAC described in ‘RFC 5869’, and is split into two logical modules,
1 called ’extract’ and ’expand’. The extract module takes an initial
1 secret and a random salt to "extract" a fixed-length pseudorandom key
1 (PRK). The second stage takes as input the previous PRK and some
1 informational data (e.g., text) and expands them into multiple keys.
1
1 Nettle’s HKDF functions are defined in ‘<nettle/hkdf.h>’. There are
1 two abstract functions for the extract and expand operations that
1 operate on any HMAC implemented via the ‘nettle_hash_update_func’, and
1 ‘nettle_hash_digest_func’ interfaces.
1
1 -- Function: void hkdf_extract (void *mac_ctx, nettle_hash_update_func
1 *update, nettle_hash_digest_func *digest, size_t
1 digest_size,size_t secret_size, const uint8_t *secret, uint8_t
1 *dst)
1 Extract a Pseudorandom Key (PRK) from a secret and a salt according
1 to HKDF. The HMAC must have been initialized, with its key being
1 the salt for the Extract operation. This function will call the
1 UPDATE and DIGEST functions passing the MAC_CTX context parameter
1 as an argument in order to compute digest of size DIGEST_SIZE.
1 Inputs are the secret SECRET of length SECRET_LENGTH. The output
1 length is fixed to DIGEST_SIZE octets, thus the output buffer DST
1 must have room for at least DIGEST_SIZE octets.
1
1 -- Function: void hkdf_expand (void *mac_ctx, nettle_hash_update_func
1 *update, nettle_hash_digest_func *digest, size_t digest_size,
1 size_t info_size, const uint8_t *info, size_t length, uint8_t
1 *dst)
1 Expand a Pseudorandom Key (PRK) to an arbitrary size according to
1 HKDF. The HMAC must have been initialized, with its key being the
1 PRK from the Extract operation. This function will call the UPDATE
1 and DIGEST functions passing the MAC_CTX context parameter as an
1 argument in order to compute digest of size DIGEST_SIZE. Inputs
1 are the info INFO of length INFO_LENGTH, and the desired derived
1 output length LENGTH. The output buffer is DST which must have
1 room for at least LENGTH octets.
1
1 6.6.2 PBKDF2
1 ------------
1
1 The most well known PBKDF is the ‘PKCS #5 PBKDF2’ described in ‘RFC
1 2898’ which uses a pseudo-random function such as HMAC-SHA1.
1
1 Nettle’s PBKDF2 functions are defined in ‘<nettle/pbkdf2.h>’. There
1 is an abstract function that operate on any PRF implemented via the
1 ‘nettle_hash_update_func’, ‘nettle_hash_digest_func’ interfaces. There
1 is also helper macros and concrete functions PBKDF2-HMAC-SHA1 and
1 PBKDF2-HMAC-SHA256. First, the abstract function:
1
1 -- Function: void pbkdf2 (void *mac_ctx, nettle_hash_update_func
1 *update, nettle_hash_digest_func *digest, size_t digest_size,
1 unsigned iterations, size_t salt_length, const uint8_t *salt,
1 size_t length, uint8_t *dst)
1 Derive symmetric key from a password according to PKCS #5 PBKDF2.
1 The PRF is assumed to have been initialized and this function will
1 call the UPDATE and DIGEST functions passing the MAC_CTX context
1 parameter as an argument in order to compute digest of size
1 DIGEST_SIZE. Inputs are the salt SALT of length SALT_LENGTH, the
1 iteration counter ITERATIONS (> 0), and the desired derived output
1 length LENGTH. The output buffer is DST which must have room for
1 at least LENGTH octets.
1
1 Like for CBC and HMAC, there is a macro to help use the function
1 correctly.
1
1 -- Macro: PBKDF2 (CTX, UPDATE, DIGEST, DIGEST_SIZE, ITERATIONS,
1 SALT_LENGTH, SALT, LENGTH, DST)
1 CTX is a pointer to a context struct passed to the UPDATE and
1 DIGEST functions (of the types ‘nettle_hash_update_func’ and
1 ‘nettle_hash_digest_func’ respectively) to implement the underlying
1 PRF with digest size of DIGEST_SIZE. Inputs are the salt SALT of
1 length SALT_LENGTH, the iteration counter ITERATIONS (> 0), and the
1 desired derived output length LENGTH. The output buffer is DST
1 which must have room for at least LENGTH octets.
1
1 6.6.3 Concrete PBKDF2 functions
1 -------------------------------
1
1 Now we come to the specialized PBKDF2 functions, which are easier to use
1 than the general PBKDF2 function.
1
1 6.6.3.1 PBKDF2-HMAC-SHA1
1 ........................
1
1 -- Function: void pbkdf2_hmac_sha1 (size_t KEY_LENGTH, const uint8_t
1 *KEY, unsigned ITERATIONS, size_t SALT_LENGTH, const uint8_t
1 *SALT, size_t LENGTH, uint8_t *DST)
1 PBKDF2 with HMAC-SHA1. Derive LENGTH bytes of key into buffer DST
1 using the password KEY of length KEY_LENGTH and salt SALT of length
1 SALT_LENGTH, with iteration counter ITERATIONS (> 0). The output
1 buffer is DST which must have room for at least LENGTH octets.
1
1 6.6.3.2 PBKDF2-HMAC-SHA256
1 ..........................
1
1 -- Function: void pbkdf2_hmac_sha256 (size_t KEY_LENGTH, const uint8_t
1 *KEY, unsigned ITERATIONS, size_t SALT_LENGTH, const uint8_t
1 *SALT, size_t LENGTH, uint8_t *DST)
1 PBKDF2 with HMAC-SHA256. Derive LENGTH bytes of key into buffer
1 DST using the password KEY of length KEY_LENGTH and salt SALT of
1 length SALT_LENGTH, with iteration counter ITERATIONS (> 0). The
1 output buffer is DST which must have room for at least LENGTH
1 octets.
1