Data Structures | Macros | Functions
bearssl_kdf.h File Reference
Include dependency graph for bearssl_kdf.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  br_hkdf_context
 HKDF context. More...


#define BR_HKDF_NO_SALT   (&br_hkdf_no_salt)
 The special "absent salt" value for HKDF. More...


void br_hkdf_init (br_hkdf_context *hc, const br_hash_class *digest_vtable, const void *salt, size_t salt_len)
 HKDF context initialization. More...
void br_hkdf_inject (br_hkdf_context *hc, const void *ikm, size_t ikm_len)
 HKDF input injection (HKDF-Extract). More...
void br_hkdf_flip (br_hkdf_context *hc)
 HKDF switch to the HKDF-Expand phase. More...
size_t br_hkdf_produce (br_hkdf_context *hc, const void *info, size_t info_len, void *out, size_t out_len)
 HKDF output production (HKDF-Expand). More...

Detailed Description

Key Derivation Functions

KDF are functions that takes a variable length input, and provide a variable length output, meant to be used to derive subkeys from a master key.


HKDF is a KDF defined by RFC 5869. It is based on HMAC, itself using an underlying hash function. Any hash function can be used, as long as it is compatible with the rules for the HMAC implementation (i.e. output size is 64 bytes or less, hash internal state size is 64 bytes or less, and the internal block length is a power of 2 between 16 and 256 bytes). HKDF has two phases:

The "salt" and "info" strings are non-secret and can be empty. Their role is normally to bind the input and output, respectively, to conventional identifiers that qualifu them within the used protocol or application.

The implementation defined in this file uses the following functions:

Note that the HKDF total output size (the number of bytes that HKDF-Expand is willing to produce) is limited: if the hash output size is n bytes, then the maximum output size is 255*n.

Macro Definition Documentation


#define BR_HKDF_NO_SALT   (&br_hkdf_no_salt)

The special "absent salt" value for HKDF.

Function Documentation

◆ br_hkdf_flip()

void br_hkdf_flip ( br_hkdf_context hc)

HKDF switch to the HKDF-Expand phase.

This call terminates the HKDF-Extract process (input injection), and starts the HKDF-Expand process (output production).

hcHKDF context.

◆ br_hkdf_init()

void br_hkdf_init ( br_hkdf_context hc,
const br_hash_class *  digest_vtable,
const void *  salt,
size_t  salt_len 

HKDF context initialization.

The underlying hash function and salt value are provided. Arbitrary salt lengths can be used.

HKDF makes a difference between a salt of length zero, and an absent salt (the latter being equivalent to a salt consisting of bytes of value zero, of the same length as the hash function output). If salt_len is zero, then this function assumes that the salt is present but of length zero. To specify an absent salt, use BR_HKDF_NO_SALT as salt parameter (salt_len is then ignored).

hcHKDF context to initialise.
digest_vtablepointer to the hash function implementation vtable.
saltHKDF-Extract salt.
salt_lenHKDF-Extract salt length (in bytes).

◆ br_hkdf_inject()

void br_hkdf_inject ( br_hkdf_context hc,
const void *  ikm,
size_t  ikm_len 

HKDF input injection (HKDF-Extract).

This function injects some more input bytes ("key material") into HKDF. This function may be called several times, after br_hkdf_init() but before br_hkdf_flip().

hcHKDF context.
ikmextra input bytes.
ikm_lennumber of extra input bytes.

◆ br_hkdf_produce()

size_t br_hkdf_produce ( br_hkdf_context hc,
const void *  info,
size_t  info_len,
void *  out,
size_t  out_len 

HKDF output production (HKDF-Expand).

Produce more output bytes from the current state. This function may be called several times, but only after br_hkdf_flip().

Returned value is the number of actually produced bytes. The total output length is limited to 255 times the output length of the underlying hash function.

hcHKDF context.
infoapplication specific information string.
info_lenapplication specific information string length (in bytes).
outdestination buffer for the HKDF output.
out_lenthe length of the requested output (in bytes).
the produced output length (in bytes).