kdf.h

All headers

Key derivation functions.

  1. CRYPTO_tls1_prf
  2. SSKDF_digest
  3. SSKDF_hmac
  4. KBKDF_ctr_hmac
  5. HKDF-specific functions
  6. EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND
  7. EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY
  8. EVP_PKEY_HKDEF_MODE_EXPAND_ONLY
  9. EVP_PKEY_CTX_hkdf_mode
  10. EVP_PKEY_CTX_set_hkdf_md
  11. EVP_PKEY_CTX_set1_hkdf_key
  12. EVP_PKEY_CTX_set1_hkdf_salt
  13. EVP_PKEY_CTX_add1_hkdf_info

CRYPTO_tls1_prf calculates out_len bytes of the TLS PRF, using digest, and writes them to out. It returns one on success and zero on error. TLS 1.2: https://datatracker.ietf.org/doc/html/rfc5246#section-5 TLS 1.{0,1}: https://datatracker.ietf.org/doc/html/rfc4346#section-5

OPENSSL_EXPORT int CRYPTO_tls1_prf(const EVP_MD *digest,
                                   uint8_t *out, size_t out_len,
                                   const uint8_t *secret, size_t secret_len,
                                   const char *label, size_t label_len,
                                   const uint8_t *seed1, size_t seed1_len,
                                   const uint8_t *seed2, size_t seed2_len);

SSKDF_digest computes the One-step key derivation using the provided digest algorithm as the backing PRF. This algorithm may be referred to as "Single-Step KDF" or "NIST Concatenation KDF" by other implementors. info_len may be zero length.

Returns a 1 on success, otherwise returns 0.

This implementation adheres to the algorithm specified in Section 4 of the NIST Special Publication 800-56C Revision 2 published on August 2020. The parameters relevant to the specification are as follows:

  • Auxillary Function H is Option 1
  • out_len, secret_len, and info_len are specified in bytes
  • out_len, secret_len, info_len each must be <= 2^30
  • out_len and secret_len > 0
  • out_len, secret_len are analogous to L and Z respectively in the specification.
  • info and info_len refer to FixedInfo in the specification.

Specification is available at https://doi.org/10.6028/NIST.SP.800-56Cr2

OPENSSL_EXPORT int SSKDF_digest(uint8_t *out_key, size_t out_len,
                                const EVP_MD *digest,
                                const uint8_t *secret, size_t secret_len,
                                const uint8_t *info, size_t info_len);

SSKDF_hmac computes the One-step key derivation using the provided digest algorithm with HMAC as the backing PRF. This algorithm may be referred to as "Single-Step KDF" or "NIST Concatenation KDF" by other implementors. salt is optional and may be NULL or zero-length. In addition info_len may be zero length.

Returns a 1 on success, otherwise returns 0.

This implementation adheres to the algorithm specified in Section 4 of the NIST Special Publication 800-56C Revision 2 published on August 2020. The parameters relevant to the specification are as follows:

  • Auxillary Function H is Option 2
  • out_len, secret_len, info_len, and salt_len are specified in bytes
  • out_len, secret_len, info_len each must be <= 2^30
  • out_len and secret_len > 0
  • out_len, secret_len are analogous to L and Z respectively in the specification.
  • info and info_len refer to FixedInfo in the specification.
  • salt and salt_len refer to salt in the specification.
  • salt or salt_len being NULL or 0 respectively will result in a default salt being used which will be an all-zero byte string whose length is equal to the length of the specified digest input block length in bytes.
OPENSSL_EXPORT int SSKDF_hmac(uint8_t *out_key, size_t out_len,
                              const EVP_MD *digest,
                              const uint8_t *secret, size_t secret_len,
                              const uint8_t *info, size_t info_len,
                              const uint8_t *salt, size_t salt_len);

KBKDF_ctr_hmac derives keying material using the KDF counter mode algorithm, using the provided key derivation key secret and fixed info info. info or info_len may be zero-length. This algorithm may be referred to as a "Key-Based Key Derivation Function in Counter Mode".

This implementation adheres to the algorithm specified in Section 4.1 of the NIST Special Publication 800-108 Revision 1 Update 1 published on August 2022. The parameters relevant to the specification are as follows:

  • out_len, secret_len, and info_len are specified in bytes
  • out_len is analogous to L in the specification.
  • r is the length of the binary representation of the counter i referred to by the specification. r is 32 bits in this implementation.
  • The 32-bit counter is big-endian in this implementation.
  • The 32-bit counter location is placed before info.
  • K_IN is analogous to secret and secret_len.
  • PRF refers to HMAC in this implementation.

Specification is available at https://doi.org/10.6028/NIST.SP.800-108r1-upd1

OPENSSL_EXPORT int KBKDF_ctr_hmac(uint8_t *out_key, size_t out_len,
                                  const EVP_MD *digest, const uint8_t *secret,
                                  size_t secret_len, const uint8_t *info,
                                  size_t info_len);

KDF support for EVP.

HKDF-specific functions.

The following functions are provided for OpenSSL compatibility. Prefer the HKDF functions in <openssl/hkdf.h>. In each, ctx must be created with EVP_PKEY_CTX_new_id with EVP_PKEY_HKDF and then initialized with EVP_PKEY_derive_init.

EVP_PKEY_HKDEF_MODE_* define "modes" for use with EVP_PKEY_CTX_hkdf_mode. The mispelling of "HKDF" as "HKDEF" is intentional for OpenSSL compatibility.

#define EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND 0
#define EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY 1
#define EVP_PKEY_HKDEF_MODE_EXPAND_ONLY 2

EVP_PKEY_CTX_hkdf_mode configures which HKDF operation to run. It returns one on success and zero on error. mode must be one of EVP_PKEY_HKDEF_MODE_*. By default, the mode is EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND.

If mode is EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND or EVP_PKEY_HKDEF_MODE_EXPAND_ONLY, the output is variable-length. EVP_PKEY_derive uses the size of the output buffer as the output length for HKDF-Expand.

WARNING: Although this API calls it a "mode", HKDF-Extract and HKDF-Expand are distinct operations with distinct inputs and distinct kinds of keys. Callers should not pass input secrets for one operation into the other.

OPENSSL_EXPORT int EVP_PKEY_CTX_hkdf_mode(EVP_PKEY_CTX *ctx, int mode);

EVP_PKEY_CTX_set_hkdf_md sets md as the digest to use with HKDF. It returns one on success and zero on error.

OPENSSL_EXPORT int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *ctx,
                                            const EVP_MD *md);

EVP_PKEY_CTX_set1_hkdf_key configures HKDF to use key_len bytes from key as the "key", described below. It returns one on success and zero on error.

Which input is the key depends on the "mode" (see EVP_PKEY_CTX_hkdf_mode). If EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND or EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY, this function specifies the input keying material (IKM) for HKDF-Extract. If EVP_PKEY_HKDEF_MODE_EXPAND_ONLY, it instead specifies the pseudorandom key (PRK) for HKDF-Expand.

OPENSSL_EXPORT int EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *ctx,
                                              const uint8_t *key,
                                              size_t key_len);

EVP_PKEY_CTX_set1_hkdf_salt configures HKDF to use salt_len bytes from salt as the salt parameter to HKDF-Extract. It returns one on success and zero on error. If performing HKDF-Expand only, this parameter is ignored.

OPENSSL_EXPORT int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *ctx,
                                               const uint8_t *salt,
                                               size_t salt_len);

EVP_PKEY_CTX_add1_hkdf_info appends info_len bytes from info to the info parameter used with HKDF-Expand. It returns one on success and zero on error. If performing HKDF-Extract only, this parameter is ignored.

OPENSSL_EXPORT int EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *ctx,
                                               const uint8_t *info,
                                               size_t info_len);