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

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

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

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.