BearSSL: bearssl_kdf.h File Reference

BearSSL

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

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

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

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