Data Structures | Functions
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...


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

Function Documentation

◆ br_hmac_get_digest()

static const br_hash_class* br_hmac_get_digest ( const br_hmac_context hc)

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

ctxHMAC context to initialise.
kcHMAC key context (already initialised with the key).
out_lenHMAC 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)

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

kcHMAC key context to initialise.
digest_vtablepointer to the hash function implementation vtable.
keypointer to the HMAC secret key.
key_lenHMAC 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).

ctxHMAC computation context.
outdestination buffer for the HMAC output.
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 230 (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.

ctxthe (already initialised) HMAC computation context.
datathe extra input bytes.
lenthe extra input length (in bytes).
min_lenminimum extra input length (in bytes).
max_lenmaximum extra input length (in bytes).
outdestination buffer for the HMAC output.
the produced value length (in bytes).

◆ br_hmac_size()

static size_t br_hmac_size ( br_hmac_context ctx)

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

ctxthe (already initialised) HMAC computation context.
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.