bearssl_hmac.h File Reference

Include dependency graph for bearssl_hmac.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	br_hmac_key_context
	HMAC key context. More...
struct	br_hmac_context
	HMAC computation context. More...

Functions
void	br_hmac_key_init (br_hmac_key_context *kc, const br_hash_class *digest_vtable, const void *key, size_t key_len)
	HMAC key context initialisation. More...
static const br_hash_class *	br_hmac_key_get_digest (const br_hmac_key_context *kc)
void	br_hmac_init (br_hmac_context *ctx, const br_hmac_key_context *kc, size_t out_len)
	HMAC computation initialisation. More...
static size_t	br_hmac_size (br_hmac_context *ctx)
	Get the HMAC output size. More...
static const br_hash_class *	br_hmac_get_digest (const br_hmac_context *hc)
void	br_hmac_update (br_hmac_context *ctx, const void *data, size_t len)
	Inject some bytes in HMAC. More...
size_t	br_hmac_out (const br_hmac_context *ctx, void *out)
	Compute the HMAC output. More...
size_t	br_hmac_outCT (const br_hmac_context *ctx, const void *data, size_t len, size_t min_len, size_t max_len, void *out)
	Constant-time HMAC computation. More...

Detailed Description

HMAC

HMAC is initialized with a key and an underlying hash function; it then fills a "key context". That context contains the processed key.

With the key context, a HMAC context can be initialized to process the input bytes and obtain the MAC output. The key context is not modified during that process, and can be reused.

IMPORTANT: HMAC shall be used only with functions that have the following properties:

• hash output size does not exceed 64 bytes;
• hash internal state size does not exceed 64 bytes;
• internal block length is a power of 2 between 16 and 256 bytes.

Function Documentation

br_hmac_get_digest()

static const br_hash_class* br_hmac_get_digest ( const br_hmac_context *  hc )

inlinestatic

br_hmac_init()

void br_hmac_init	(	br_hmac_context *	ctx,
		const br_hmac_key_context *	kc,
		size_t	out_len
	)

HMAC computation initialisation.

Initialise a HMAC context with a key context. The key context is unmodified. Relevant data from the key context is immediately copied; the key context can thus be independently reused, modified or released without impacting this HMAC computation.

An explicit output length can be specified; the actual output length will be the minimum of that value and the natural HMAC output length. If out_len is 0, then the natural HMAC output length is selected. The "natural output length" is the output length of the underlying hash function.

Parameters

ctx	HMAC context to initialise.
kc	HMAC key context (already initialised with the key).
out_len	HMAC output length (0 to select "natural length").

br_hmac_key_get_digest()

static const br_hash_class* br_hmac_key_get_digest ( const br_hmac_key_context *  kc )

inlinestatic

br_hmac_key_init()

void br_hmac_key_init	(	br_hmac_key_context *	kc,
		const br_hash_class *	digest_vtable,
		const void *	key,
		size_t	key_len
	)

HMAC key context initialisation.

Initialise the key context with the provided key, using the hash function identified by digest_vtable. This supports arbitrary key lengths.

Parameters

kc	HMAC key context to initialise.
digest_vtable	pointer to the hash function implementation vtable.
key	pointer to the HMAC secret key.
key_len	HMAC secret key length (in bytes).

br_hmac_out()

size_t br_hmac_out	(	const br_hmac_context *	ctx,
		void *	out
	)

Compute the HMAC output.

The destination buffer MUST be large enough to accommodate the result; its length is at most the "natural length" of HMAC (i.e. the output length of the underlying hash function). The context is NOT modified; further bytes may be processed. Thus, "partial HMAC" values can be efficiently obtained.

Returned value is the output length (in bytes).

Parameters

ctx	HMAC computation context.
out	destination buffer for the HMAC output.

Returns

the produced value length (in bytes).

br_hmac_outCT()

size_t br_hmac_outCT	(	const br_hmac_context *	ctx,
		const void *	data,
		size_t	len,
		size_t	min_len,
		size_t	max_len,
		void *	out
	)

Constant-time HMAC computation.

This function compute the HMAC output in constant time. Some extra input bytes are processed, then the output is computed. The extra input consists in the len bytes pointed to by data. The len parameter must lie between min_len and max_len (inclusive); max_len bytes are actually read from data. Computing time (and memory access pattern) will not depend upon the data byte contents or the value of len.

The output is written in the out buffer, that MUST be large enough to receive it.

The difference max_len - min_len MUST be less than 2³⁰ (i.e. about one gigabyte).

This function computes the output properly only if the underlying hash function uses MD padding (i.e. MD5, SHA-1, SHA-224, SHA-256, SHA-384 or SHA-512).

The provided context is NOT modified.

Parameters

ctx	the (already initialised) HMAC computation context.
data	the extra input bytes.
len	the extra input length (in bytes).
min_len	minimum extra input length (in bytes).
max_len	maximum extra input length (in bytes).
out	destination buffer for the HMAC output.

Returns

the produced value length (in bytes).

br_hmac_size()

static size_t br_hmac_size ( br_hmac_context *  ctx )

inlinestatic

Get the HMAC output size.

The HMAC output size is the number of bytes that will actually be produced with br_hmac_out() with the provided context. This function MUST NOT be called on a non-initialised HMAC computation context. The returned value is the minimum of the HMAC natural length (output size of the underlying hash function) and the out_len parameter which was used with the last br_hmac_init() call on that context (if the initialisation out_len parameter was 0, then this function will return the HMAC natural length).

Parameters

ctx	the (already initialised) HMAC computation context.

Returns

the HMAC actual output size.

br_hmac_update()

void br_hmac_update	(	br_hmac_context *	ctx,
		const void *	data,
		size_t	len
	)

Inject some bytes in HMAC.

The provided len bytes are injected as extra input in the HMAC computation incarnated by the ctx HMAC context. It is acceptable that len is zero, in which case data is ignored (and may be NULL) and this function does nothing.