hkdf.h

HMAC-based Key Derivation Function (HKDF) \par Reference: RFC 5869.

HKDF is used in TLS 1.3 for all key derivation operations.

Author

Claude Code

Functions

bool tls_hkdf_extract(uint8_t hash_algorithm, const uint8_t *salt, size_t salt_len, const uint8_t *ikm, size_t ikm_len, uint8_t *prk)

HKDF-Extract: Extract a fixed-length pseudorandom key.

PRK = HMAC-Hash(salt, IKM)

Parameters:

  • hash_algorithm – Hash algorithm (TLS_HASH_SHA256, etc.)

  • salt – Optional salt value (can be NULL for zero-length)

  • salt_len – Length of salt in bytes

  • ikm – Input keying material

  • ikm_len – Length of IKM in bytes

  • prk – Output pseudorandom key (hash_len bytes)

Returns:

true on success, false on failure

bool tls_hkdf_expand(uint8_t hash_algorithm, const uint8_t *prk, size_t prk_len, const uint8_t *info, size_t info_len, uint8_t *okm, size_t okm_len)

HKDF-Expand: Expand PRK to desired length.

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

Parameters:

  • hash_algorithm – Hash algorithm (TLS_HASH_SHA256, etc.)

  • prk – Pseudorandom key from HKDF-Extract

  • prk_len – Length of PRK (typically hash output size)

  • info – Optional context and application specific information

  • info_len – Length of info

  • okm – Output keying material

  • okm_len – Desired length of OKM (max: 255 * hash_len)

Returns:

true on success, false on failure

bool tls_hkdf_expand_label(uint8_t hash_algorithm, 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)

HKDF-Expand-Label: TLS 1.3 specific key derivation.

Derives keying material from a secret using HKDF with TLS 1.3 label formatting.

HkdfLabel structure: struct { uint16 length = Length; opaque label<7..255> = “tls13 “ + Label; opaque context<0..255> = Context; } HkdfLabel;

Parameters:

  • hash_algorithm – Hash algorithm (TLS_HASH_SHA256, etc.)

  • secret – Input secret

  • secret_len – Length of secret

  • label – ASCII label string (without “tls13 “ prefix)

  • label_len – Length of label

  • context – Optional context (typically transcript hash)

  • context_len – Length of context

  • out – Output buffer

  • out_len – Desired output length

Returns:

true on success, false on failure

bool tls_derive_secret(uint8_t hash_algorithm, const uint8_t *secret, size_t secret_len, const char *label, size_t label_len, const uint8_t *transcript_hash, size_t transcript_hash_len, uint8_t *out)

Derive-Secret: TLS 1.3 transcript-based key derivation.

Convenience function: Derive-Secret(Secret, Label, Messages) = HKDF-Expand-Label(Secret, Label, Transcript-Hash(Messages), Hash.length)

Parameters:

  • hash_algorithm – Hash algorithm

  • secret – Input secret

  • secret_len – Length of secret

  • label – ASCII label string

  • label_len – Length of label

  • transcript_hash – Hash of handshake messages

  • transcript_hash_len – Length of transcript hash (typically 32 for SHA256)

  • out – Output buffer (hash_len bytes)

Returns:

true on success, false on failure