BearSSL: bearssl_hmac.h File Reference

BearSSL

Loading...
Searching...
No Matches
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...

## 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.
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.
static size_t | br_hmac_size (br_hmac_context *ctx)
| Get the HMAC output size.
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.
size_t | br_hmac_out (const br_hmac_context *ctx, void *out)
| Compute the HMAC output.
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.

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

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.