KDF#

Key derivation functions (KDFs) are used to derive cryptographically strong keys from an initial secret value.

HKDF#

HMAC-based Extract-and-Expand Key Derivation Function (HKDF) RFC 5869.

Similar to RFC 5869, the following descriptions uses the term HashLen to denote the output length of the hash function of a concrete instantiation of HKDF.

The following instantiations are supported:

BLAKE2b (HashLen = 64)
BLAKE2s (HashLen = 32)
SHA2-256 (HashLen = 32)
SHA2-384 (HashLen = 48)
SHA2-512 (HashLen = 64)

Available Implementations#

#include "Hacl_HKDF.h"

#include "Hacl_HKDF_Blake2b_256.h"

API Reference#

Example (SHA2-256)

#define HACL_KDF_HKDF_BLAKE2B_PRK_LEN 64
#define HACL_KDF_HKDF_BLAKE2S_PRK_LEN 32
#define HACL_KDF_HKDF_SHA2_256_PRK_LEN 32
#define HACL_KDF_HKDF_SHA2_512_PRK_LEN 64

// Example: We assume that we have some input keying material ...
uint8_t ikm[128];
uint32_t ikm_len = 128;
generate_random(ikm, 128);

// ... and a salt.
const char* salt = "example";
uint32_t salt_len = strlen(salt);

// Extract a fixed-length pseudo-random key from `ikm`.
uint8_t prk[HACL_KDF_HKDF_SHA2_256_PRK_LEN];

Hacl_HKDF_extract_sha2_256(prk, (uint8_t*)salt, salt_len, ikm, ikm_len);

// Expand pseudo-random key to desired length
// and write it to `okm` (output keying material).
uint8_t okm[1337];
uint32_t okm_len = 1337;

// We don't provide specific information here.
const char* info = "";
uint32_t info_len = 0;

Hacl_HKDF_expand_sha2_256(okm,
                          prk,
                          HACL_KDF_HKDF_SHA2_256_PRK_LEN,
                          (uint8_t*)info,
                          info_len,
                          okm_len);

BLAKE2b#

void Hacl_HKDF_extract_blake2b_32(uint8_t *prk, uint8_t *salt, uint32_t saltlen, uint8_t *ikm, uint32_t ikmlen)#

Extract a fixed-length pseudorandom key from input keying material.

Parameters

prk – Pointer to HashLen bytes of memory where pseudorandom key is written to.
salt – Pointer to saltlen bytes of memory where salt value is read from.
saltlen – Length of salt value.
ikm – Pointer to ikmlen bytes of memory where input keying material is read from.
ikmlen – Length of input keying material.

void Hacl_HKDF_Blake2b_256_extract_blake2b_256(uint8_t *prk, uint8_t *salt, uint32_t saltlen, uint8_t *ikm, uint32_t ikmlen)#

Extract a fixed-length pseudorandom key from input keying material.

Parameters

prk – Pointer to HashLen bytes of memory where pseudorandom key is written to.
salt – Pointer to saltlen bytes of memory where salt value is read from.
saltlen – Length of salt value.
ikm – Pointer to ikmlen bytes of memory where input keying material is read from.
ikmlen – Length of input keying material.

#include "Hacl_HKDF.h"

void Hacl_HKDF_expand_blake2b_32(uint8_t *okm, uint8_t *prk, uint32_t prklen, uint8_t *info, uint32_t infolen, uint32_t len)#

Expand pseudorandom key to desired length.

Parameters

okm – Pointer to len bytes of memory where output keying material is written to.
prk – Pointer to at least HashLen bytes of memory where pseudorandom key is read from. Usually, this points to the output from the extract step.
prklen – Length of pseudorandom key.
info – Pointer to infolen bytes of memory where context and application specific information is read from. Can be a zero-length string.
infolen – Length of context and application specific information.
len – Length of output keying material.

#include "Hacl_HKDF_Blake2b_256.h"

void Hacl_HKDF_Blake2b_256_expand_blake2b_256(uint8_t *okm, uint8_t *prk, uint32_t prklen, uint8_t *info, uint32_t infolen, uint32_t len)#

Expand pseudorandom key to desired length.

Parameters

okm – Pointer to len bytes of memory where output keying material is written to.
prk – Pointer to at least HashLen bytes of memory where pseudorandom key is read from. Usually, this points to the output from the extract step.
prklen – Length of pseudorandom key.
info – Pointer to infolen bytes of memory where context and application specific information is read from. Can be a zero-length string.
infolen – Length of context and application specific information.
len – Length of output keying material.

BLAKE2s#

#include "Hacl_HKDF.h"

void Hacl_HKDF_extract_blake2s_32(uint8_t *prk, uint8_t *salt, uint32_t saltlen, uint8_t *ikm, uint32_t ikmlen)#

Extract a fixed-length pseudorandom key from input keying material.

Parameters

prk – Pointer to HashLen bytes of memory where pseudorandom key is written to.
salt – Pointer to saltlen bytes of memory where salt value is read from.
saltlen – Length of salt value.
ikm – Pointer to ikmlen bytes of memory where input keying material is read from.
ikmlen – Length of input keying material.

#include "Hacl_HKDF_Blake2s_128.h"

void Hacl_HKDF_Blake2s_128_extract_blake2s_128(uint8_t *prk, uint8_t *salt, uint32_t saltlen, uint8_t *ikm, uint32_t ikmlen)#

Extract a fixed-length pseudorandom key from input keying material.

Parameters

prk – Pointer to HashLen bytes of memory where pseudorandom key is written to.
salt – Pointer to saltlen bytes of memory where salt value is read from.
saltlen – Length of salt value.
ikm – Pointer to ikmlen bytes of memory where input keying material is read from.
ikmlen – Length of input keying material.

#include "Hacl_HKDF.h"

void Hacl_HKDF_expand_blake2s_32(uint8_t *okm, uint8_t *prk, uint32_t prklen, uint8_t *info, uint32_t infolen, uint32_t len)#

Expand pseudorandom key to desired length.

Parameters

okm – Pointer to len bytes of memory where output keying material is written to.
prk – Pointer to at least HashLen bytes of memory where pseudorandom key is read from. Usually, this points to the output from the extract step.
prklen – Length of pseudorandom key.
info – Pointer to infolen bytes of memory where context and application specific information is read from. Can be a zero-length string.
infolen – Length of context and application specific information.
len – Length of output keying material.

#include "Hacl_HKDF_Blake2s_128.h"

void Hacl_HKDF_Blake2s_128_expand_blake2s_128(uint8_t *okm, uint8_t *prk, uint32_t prklen, uint8_t *info, uint32_t infolen, uint32_t len)#

Expand pseudorandom key to desired length.

Parameters

okm – Pointer to len bytes of memory where output keying material is written to.
prk – Pointer to at least HashLen bytes of memory where pseudorandom key is read from. Usually, this points to the output from the extract step.
prklen – Length of pseudorandom key.
info – Pointer to infolen bytes of memory where context and application specific information is read from. Can be a zero-length string.
infolen – Length of context and application specific information.
len – Length of output keying material.

SHA2-256#

#include "Hacl_HKDF.h"

void Hacl_HKDF_extract_sha2_256(uint8_t *prk, uint8_t *salt, uint32_t saltlen, uint8_t *ikm, uint32_t ikmlen)#

Extract a fixed-length pseudorandom key from input keying material.

Parameters

prk – Pointer to HashLen bytes of memory where pseudorandom key is written to.
salt – Pointer to saltlen bytes of memory where salt value is read from.
saltlen – Length of salt value.
ikm – Pointer to ikmlen bytes of memory where input keying material is read from.
ikmlen – Length of input keying material.

void Hacl_HKDF_expand_sha2_256(uint8_t *okm, uint8_t *prk, uint32_t prklen, uint8_t *info, uint32_t infolen, uint32_t len)#

Expand pseudorandom key to desired length.

Parameters

okm – Pointer to len bytes of memory where output keying material is written to.
prk – Pointer to at least HashLen bytes of memory where pseudorandom key is read from. Usually, this points to the output from the extract step.
prklen – Length of pseudorandom key.
info – Pointer to infolen bytes of memory where context and application specific information is read from. Can be a zero-length string.
infolen – Length of context and application specific information.
len – Length of output keying material.

SHA2-384#

#include "Hacl_HKDF.h"

void Hacl_HKDF_extract_sha2_384(uint8_t *prk, uint8_t *salt, uint32_t saltlen, uint8_t *ikm, uint32_t ikmlen)#

Extract a fixed-length pseudorandom key from input keying material.

Parameters

prk – Pointer to HashLen bytes of memory where pseudorandom key is written to.
salt – Pointer to saltlen bytes of memory where salt value is read from.
saltlen – Length of salt value.
ikm – Pointer to ikmlen bytes of memory where input keying material is read from.
ikmlen – Length of input keying material.

void Hacl_HKDF_expand_sha2_384(uint8_t *okm, uint8_t *prk, uint32_t prklen, uint8_t *info, uint32_t infolen, uint32_t len)#

Expand pseudorandom key to desired length.

Parameters

okm – Pointer to len bytes of memory where output keying material is written to.
prk – Pointer to at least HashLen bytes of memory where pseudorandom key is read from. Usually, this points to the output from the extract step.
prklen – Length of pseudorandom key.
info – Pointer to infolen bytes of memory where context and application specific information is read from. Can be a zero-length string.
infolen – Length of context and application specific information.
len – Length of output keying material.

SHA2-512#

#include "Hacl_HKDF.h"

void Hacl_HKDF_extract_sha2_512(uint8_t *prk, uint8_t *salt, uint32_t saltlen, uint8_t *ikm, uint32_t ikmlen)#

Extract a fixed-length pseudorandom key from input keying material.

Parameters

prk – Pointer to HashLen bytes of memory where pseudorandom key is written to.
salt – Pointer to saltlen bytes of memory where salt value is read from.
saltlen – Length of salt value.
ikm – Pointer to ikmlen bytes of memory where input keying material is read from.
ikmlen – Length of input keying material.

void Hacl_HKDF_expand_sha2_512(uint8_t *okm, uint8_t *prk, uint32_t prklen, uint8_t *info, uint32_t infolen, uint32_t len)#

Expand pseudorandom key to desired length.

Parameters

okm – Pointer to len bytes of memory where output keying material is written to.
prk – Pointer to at least HashLen bytes of memory where pseudorandom key is read from. Usually, this points to the output from the extract step.
prklen – Length of pseudorandom key.
info – Pointer to infolen bytes of memory where context and application specific information is read from. Can be a zero-length string.
infolen – Length of context and application specific information.
len – Length of output keying material.

Versions

KDF

Contents

KDF#

HKDF#

Available Implementations#

API Reference#

BLAKE2b#

BLAKE2s#

SHA2-256#

SHA2-384#

SHA2-512#