KDF

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"

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. 

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

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

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.

Contents