HKDF - HMAC-based Extract-and-Expand Key Derivation Function

HKDF is used to generate derived keys from an input key. The first step, "extract", takes the input key material and generates a fixed-length pseudo random key (PRK). The intention of this step is to concentrate the entropy from a longer input key of possibly lower entropy. The extract step is optional. The second step, "expand", generates derived keys of arbitrary length from the PRK. The derived keys can be different by using different additional information for each derived key.

A typical use case for HKDF is converting shared secrets to encryption keys. For example, HKDF is used to generate the identity key in Eddystone.

HKDF frontend and backends

The HKDF frontend (HMAC based Key Derivation Function (HKDF) related functions) provides a common API that is independent of the crypto backends. The application has control of the memory usage, as most of the work memory is part of the context structure that is allocated by the user and provided to the HKDF API.

The nrf_crypto HKDF module can use any hash function that is supported by the underlying HMAC - Hash-based message authentication code module. There is no dedicated backend configuration for the HKDF module.

Note

Refer to Available backends for backend configuration.

HKDF usage

1. Enable nrf_crypto backend for HMAC in the SDK configuration header file. See Configuring nrf_crypto frontend and backends.
2. Initialize nrf_crypto using nrf_crypto_init.
3. Optionally, create a context of type nrf_crypto_hmac_context_t. Alternatively, the context can be allocated internally using Dynamic memory management module.
4. Call nrf_crypto_hkdf_calculate with pointers to output and input buffers, optional context, and constant info structure. The info structure defines the hash type, and is either g_nrf_crypto_hmac_sha256_info for SHA-256 or g_nrf_crypto_hmac_sha512_info for SHA-512. The mode parameter should normally be set to NRF_CRYPTO_HKDF_EXTRACT_AND_EXPAND, but can be set to NRF_CRYPTO_HKDF_EXPAND_ONLY in order to skip the initial extract step.

The following example code demonstrates how to calculate HKDF SHA-256.

uint8_t ikm[] = {0x00, 0x00};
uint8_t salt[] = {0x00, 0x00, 0x00};
uint8_t ainfo[] = {0x00, 0x00, 0x00, 0x00};
uint8_t okm[8];
size_t okm_len = sizeof(okm);
nrf_crypto_hmac_context_t context;
uint32_t err_code;

// Initialize crypto library before using any crypto functionality.
err_code = nrf_crypto_init();
APP_ERROR_CHECK(err_code);

err_code = nrf_crypto_hkdf_calculate(
 &context, // Optional context structure.
 &g_nrf_crypto_hmac_sha256_info, // Pointer to constant info structure.
 okm, // Pointer to output key material buffer.
 &okm_len, // Updated during the call.
 ikm, // Pointer to input key material.
 sizeof(ikm), // Length of input key material.
 salt, // Pointer to salt buffer.
 sizeof(salt), // Length of salt buffer in bytes.
 ainfo, // Pointer to additional info buffer.
 sizeof(ainfo), // Length of additional info buffer.
 NRF_CRYPTO_HKDF_EXTRACT_AND_EXPAND); // Use both extract and expand stages.
APP_ERROR_CHECK(err_code);

HKDF example project

Refer to HKDF Example for a usage example of this library.

For an example showing the verification procedure of HKDF, see Test Example.