File syn_hkdf.h¶

FileList > crypto > syn_hkdf.h

HMAC-based Extract-and-Expand Key Derivation Function (HKDF-SHA256, RFC 5869) & TLS 1.3 HKDF-Expand-Label.

#include "syn_hmac.h"
#include "syn_sha256.h"
#include "syn_sha512.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Public Functions¶

Type	Name
bool	syn_hkdf (const uint8_t * salt, size_t salt_len, const uint8_t * ikm, size_t ikm_len, const uint8_t * info, size_t info_len, uint8_t * okm_out, size_t okm_len) Complete HKDF-SHA256 (Extract then Expand).
bool	syn_hkdf_expand (const uint8_t * prk, size_t prk_len, const uint8_t * info, size_t info_len, uint8_t * okm_out, size_t okm_len) HKDF-SHA256 Expand step (RFC 5869 Section 2.3).
bool	syn_hkdf_expand_label (const uint8_t * secret, size_t secret_len, const char * label, size_t label_len, const uint8_t * context, size_t context_len, uint8_t * out, size_t out_len) TLS 1.3 HKDF-Expand-Label with SHA-256 (RFC 8446 Section 7.1).
void	syn_hkdf_extract (const uint8_t * salt, size_t salt_len, const uint8_t * ikm, size_t ikm_len, uint8_t prk_out) HKDF-SHA256 Extract step (RFC 5869 Section 2.2).
bool	syn_hkdf_sha384 (const uint8_t * salt, size_t salt_len, const uint8_t * ikm, size_t ikm_len, const uint8_t * info, size_t info_len, uint8_t * okm_out, size_t okm_len) Complete HKDF-SHA384 (Extract then Expand).
bool	syn_hkdf_sha384_expand (const uint8_t * prk, size_t prk_len, const uint8_t * info, size_t info_len, uint8_t * okm_out, size_t okm_len) HKDF-SHA384 Expand step (RFC 5869 Section 2.3).
bool	syn_hkdf_sha384_expand_label (const uint8_t * secret, size_t secret_len, const char * label, size_t label_len, const uint8_t * context, size_t context_len, uint8_t * out, size_t out_len) TLS 1.3 HKDF-Expand-Label with SHA-384 (RFC 8446 Section 7.1).
void	syn_hkdf_sha384_extract (const uint8_t * salt, size_t salt_len, const uint8_t * ikm, size_t ikm_len, uint8_t prk_out) HKDF-SHA384 Extract step (RFC 5869 Section 2.2).
bool	syn_hkdf_sha512 (const uint8_t * salt, size_t salt_len, const uint8_t * ikm, size_t ikm_len, const uint8_t * info, size_t info_len, uint8_t * okm_out, size_t okm_len) Complete HKDF-SHA512 (Extract then Expand).
bool	syn_hkdf_sha512_expand (const uint8_t * prk, size_t prk_len, const uint8_t * info, size_t info_len, uint8_t * okm_out, size_t okm_len) HKDF-SHA512 Expand step (RFC 5869 Section 2.3).
bool	syn_hkdf_sha512_expand_label (const uint8_t * secret, size_t secret_len, const char * label, size_t label_len, const uint8_t * context, size_t context_len, uint8_t * out, size_t out_len) TLS 1.3 HKDF-Expand-Label with SHA-512 (RFC 8446 Section 7.1).
void	syn_hkdf_sha512_extract (const uint8_t * salt, size_t salt_len, const uint8_t * ikm, size_t ikm_len, uint8_t prk_out) HKDF-SHA512 Extract step (RFC 5869 Section 2.2).

Public Functions Documentation¶

function syn_hkdf¶

Complete HKDF-SHA256 (Extract then Expand).

bool syn_hkdf (
    const uint8_t * salt,
    size_t salt_len,
    const uint8_t * ikm,
    size_t ikm_len,
    const uint8_t * info,
    size_t info_len,
    uint8_t * okm_out,
    size_t okm_len
)

Parameters:

salt Salt value (optional).
salt_len Salt length.
ikm Input keying material.
ikm_len IKM length.
info Context info (optional).
info_len Info length.
okm_out [out] Output keying material.
okm_len Desired output length.

Returns:

true on success.

function syn_hkdf_expand¶

HKDF-SHA256 Expand step (RFC 5869 Section 2.3).

bool syn_hkdf_expand (
    const uint8_t * prk,
    size_t prk_len,
    const uint8_t * info,
    size_t info_len,
    uint8_t * okm_out,
    size_t okm_len
)

OKM = HKDF-Expand(PRK, info, L)

Parameters:

prk Pseudorandom Key (at least 32 bytes).
prk_len PRK length in bytes.
info Optional context and application specific information.
info_len Info length in bytes.
okm_out [out] Output keying material buffer.
okm_len Desired length of output keying material (max 255 * 32 = 8160 bytes).

Returns:

true on success, false on invalid parameters.

function syn_hkdf_expand_label¶

TLS 1.3 HKDF-Expand-Label with SHA-256 (RFC 8446 Section 7.1).

bool syn_hkdf_expand_label (
    const uint8_t * secret,
    size_t secret_len,
    const char * label,
    size_t label_len,
    const uint8_t * context,
    size_t context_len,
    uint8_t * out,
    size_t out_len
)

Parameters:

secret Secret key (at least 32 bytes).
secret_len Secret length.
label Label string (e.g. "c hs traffic", "s hs traffic", "derived", etc.).
label_len Label length (excluding null terminator).
context Transcript hash context bytes (or NULL if 0-length).
context_len Context length (e.g. 32 bytes for SHA-256 transcript hash).
out [out] Output key buffer.
out_len Desired output key length.

Returns:

true on success.

function syn_hkdf_extract¶

HKDF-SHA256 Extract step (RFC 5869 Section 2.2).

void syn_hkdf_extract (
    const uint8_t * salt,
    size_t salt_len,
    const uint8_t * ikm,
    size_t ikm_len,
    uint8_t prk_out
)

PRK = HMAC-Hash(salt, IKM)

Parameters:

salt Salt value (if NULL, a string of 32 zero bytes is used).
salt_len Salt length in bytes.
ikm Input keying material.
ikm_len IKM length in bytes.
prk_out [out] Output Pseudorandom Key buffer (must be at least 32 bytes).

function syn_hkdf_sha384¶

Complete HKDF-SHA384 (Extract then Expand).

bool syn_hkdf_sha384 (
    const uint8_t * salt,
    size_t salt_len,
    const uint8_t * ikm,
    size_t ikm_len,
    const uint8_t * info,
    size_t info_len,
    uint8_t * okm_out,
    size_t okm_len
)

Parameters:

salt Salt value (optional).
salt_len Salt length.
ikm Input keying material.
ikm_len IKM length.
info Context info (optional).
info_len Info length.
okm_out [out] Output keying material.
okm_len Desired output length.

Returns:

true on success.

function syn_hkdf_sha384_expand¶

HKDF-SHA384 Expand step (RFC 5869 Section 2.3).

bool syn_hkdf_sha384_expand (
    const uint8_t * prk,
    size_t prk_len,
    const uint8_t * info,
    size_t info_len,
    uint8_t * okm_out,
    size_t okm_len
)

Parameters:

prk Pseudorandom Key (at least 48 bytes).
prk_len PRK length in bytes.
info Optional context and application specific information.
info_len Info length in bytes.
okm_out [out] Output keying material buffer.
okm_len Desired length of output keying material (max 255 * 48 = 12240 bytes).

Returns:

true on success, false on invalid parameters.

function syn_hkdf_sha384_expand_label¶

TLS 1.3 HKDF-Expand-Label with SHA-384 (RFC 8446 Section 7.1).

bool syn_hkdf_sha384_expand_label (
    const uint8_t * secret,
    size_t secret_len,
    const char * label,
    size_t label_len,
    const uint8_t * context,
    size_t context_len,
    uint8_t * out,
    size_t out_len
)

Parameters:

secret Secret key (at least 48 bytes).
secret_len Secret length.
label Label string.
label_len Label length (excluding null terminator).
context Transcript hash context bytes (or NULL if 0-length).
context_len Context length (e.g. 48 bytes for SHA-384 transcript hash).
out [out] Output key buffer.
out_len Desired output key length.

Returns:

true on success.

function syn_hkdf_sha384_extract¶

HKDF-SHA384 Extract step (RFC 5869 Section 2.2).

void syn_hkdf_sha384_extract (
    const uint8_t * salt,
    size_t salt_len,
    const uint8_t * ikm,
    size_t ikm_len,
    uint8_t prk_out
)

Parameters:

salt Salt value (if NULL, a string of 48 zero bytes is used).
salt_len Salt length in bytes.
ikm Input keying material.
ikm_len IKM length in bytes.
prk_out [out] Output Pseudorandom Key buffer (must be at least 48 bytes).

function syn_hkdf_sha512¶

Complete HKDF-SHA512 (Extract then Expand).

bool syn_hkdf_sha512 (
    const uint8_t * salt,
    size_t salt_len,
    const uint8_t * ikm,
    size_t ikm_len,
    const uint8_t * info,
    size_t info_len,
    uint8_t * okm_out,
    size_t okm_len
)

Parameters:

salt Salt value (optional).
salt_len Salt length.
ikm Input keying material.
ikm_len IKM length.
info Context info (optional).
info_len Info length.
okm_out [out] Output keying material.
okm_len Desired output length.

Returns:

true on success.

function syn_hkdf_sha512_expand¶

HKDF-SHA512 Expand step (RFC 5869 Section 2.3).

bool syn_hkdf_sha512_expand (
    const uint8_t * prk,
    size_t prk_len,
    const uint8_t * info,
    size_t info_len,
    uint8_t * okm_out,
    size_t okm_len
)

Parameters:

prk Pseudorandom Key (at least 64 bytes).
prk_len PRK length in bytes.
info Optional context and application specific information.
info_len Info length in bytes.
okm_out [out] Output keying material buffer.
okm_len Desired length of output keying material (max 255 * 64 = 16320 bytes).

Returns:

true on success, false on invalid parameters.

function syn_hkdf_sha512_expand_label¶

TLS 1.3 HKDF-Expand-Label with SHA-512 (RFC 8446 Section 7.1).

bool syn_hkdf_sha512_expand_label (
    const uint8_t * secret,
    size_t secret_len,
    const char * label,
    size_t label_len,
    const uint8_t * context,
    size_t context_len,
    uint8_t * out,
    size_t out_len
)

Parameters:

secret Secret key (at least 64 bytes).
secret_len Secret length.
label Label string.
label_len Label length (excluding null terminator).
context Transcript hash context bytes (or NULL if 0-length).
context_len Context length.
out [out] Output key buffer.
out_len Desired output key length.

Returns:

true on success.

function syn_hkdf_sha512_extract¶

HKDF-SHA512 Extract step (RFC 5869 Section 2.2).

void syn_hkdf_sha512_extract (
    const uint8_t * salt,
    size_t salt_len,
    const uint8_t * ikm,
    size_t ikm_len,
    uint8_t prk_out
)

Parameters:

salt Salt value (if NULL, a string of 64 zero bytes is used).
salt_len Salt length in bytes.
ikm Input keying material.
ikm_len IKM length in bytes.
prk_out [out] Output Pseudorandom Key buffer (must be at least 64 bytes).

The documentation for this class was generated from the following file src/syntropic/crypto/syn_hkdf.h