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...
struct	br_shake_context
	SHAKE 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...
void	br_shake_init (br_shake_context *sc, int security_level)
	SHAKE context initialization. More...
void	br_shake_inject (br_shake_context *sc, const void *data, size_t len)
	SHAKE input injection. More...
void	br_shake_flip (br_shake_context *hc)
	SHAKE switch to production phase. More...
void	br_shake_produce (br_shake_context *sc, void *out, size_t len)
	SHAKE output production. 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.

SHAKE

SHAKE is defined in FIPS 202 under two versions: SHAKE128 and SHAKE256, offering an alleged "security level" of 128 and 256 bits, respectively (SHAKE128 is about 20 to 25% faster than SHAKE256). SHAKE internally relies on the Keccak family of sponge functions, not on any externally provided hash function. Contrary to HKDF, SHAKE does not have a concept of either a "salt" or an "info" string. The API consists in four functions:

• br_shake_init(): initialize a SHAKE context for a given security level.
• br_shake_inject(): inject more input bytes. This function may be called repeatedly if the input data is provided by chunks.
• br_shake_flip(): end the data injection process, and start the data production process.
• br_shake_produce(): get the next bytes of output. This function may be called several times to obtain the full output by chunks.

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

br_shake_flip()

void br_shake_flip

(

br_shake_context *

hc

)

SHAKE switch to production phase.

This call terminates the input injection process, and starts the output production process.

Parameters

sc	SHAKE context.

br_shake_init()

void br_shake_init	(	br_shake_context *	sc,
		int	security_level
	)

SHAKE context initialization.

The context is initialized for the provided "security level". Internally, this sets the "capacity" to twice the security level; thus, for SHAKE128, the security_level parameter should be 128, which corresponds to a 256-bit capacity.

Allowed security levels are all multiples of 32, from 32 to 768, inclusive. Larger security levels imply lower performance; levels beyond 256 bits don't make much sense. Standard levels are 128 and 256 bits (for SHAKE128 and SHAKE256, respectively).

Parameters

sc	SHAKE context to initialise.
security_level	security level (in bits).

br_shake_inject()

void br_shake_inject	(	br_shake_context *	sc,
		const void *	data,
		size_t	len
	)

SHAKE input injection.

This function injects some more input bytes ("key material") into SHAKE. This function may be called several times, after br_shake_init() but before br_shake_flip().

Parameters

sc	SHAKE context.
data	extra input bytes.
len	number of extra input bytes.

br_shake_produce()

void br_shake_produce	(	br_shake_context *	sc,
		void *	out,
		size_t	len
	)

SHAKE output production.

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

There is no practical limit to the number of bytes that may be produced.

Parameters

sc	SHAKE context.
out	destination buffer for the SHAKE output.
len	the length of the requested output (in bytes).