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...

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

Functions
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

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:

• HKDF-Extract: the input data in ingested, along with a "salt" value.
• HKDF-Expand: the output is produced, from the result of processing the input and salt, and using an extra non-secret parameter called "info".

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:

• br_hkdf_init(): initialize an HKDF context, with a hash function, and the salt. This starts the HKDF-Extract process.
• br_hkdf_inject(): inject more input bytes. This function may be called repeatedly if the input data is provided by chunks.
• br_hkdf_flip(): end the HKDF-Extract process, and start the HKDF-Expand process.
• br_hkdf_produce(): get the next bytes of output. This function may be called several times to obtain the full output by chunks. For correct HKDF processing, the same "info" string must be provided for each call.

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

BR_HKDF_NO_SALT

#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).

Parameters

hc	HKDF 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).

Parameters

hc	HKDF context to initialise.
digest_vtable	pointer to the hash function implementation vtable.
salt	HKDF-Extract salt.
salt_len	HKDF-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().

Parameters

hc	HKDF context.
ikm	extra input bytes.
ikm_len	number 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.

Parameters

hc	HKDF context.
info	application specific information string.
info_len	application specific information string length (in bytes).
out	destination buffer for the HKDF output.
out_len	the length of the requested output (in bytes).

Returns

the produced output length (in bytes).