hkdf.h File Reference

HKDF-SHA256 (RFC 5869) and TLS 1.3 HKDF-Expand-Label (RFC 8446 sec 7.1). More...

#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	HkdfNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Macros
#define	PROTOCORE_HKDF_HASH_LEN   32
	HKDF-SHA256 output block length (== SHA-256 digest length).
#define	PROTOCORE_HKDF_LABEL_PREFIX   "tls13 "
	The RFC 8446 sec 7.1 HKDF-Expand-Label prefix used by TLS 1.3 and QUIC. DTLS 1.3 overrides it with "dtls13" (RFC 9147 sec 5.9); callers that need it pass it explicitly.

Functions
	PROTOCORE_NS_LAYOUT (HkdfNs, extract, expand, expand_label, expand_label_ctx)
proto_bool	protocore_hkdf_extract (uint8_t *work, const uint8_t *salt, size_t salt_len, const uint8_t *ikm, size_t ikm_len, uint8_t *prk)
	PRK = HMAC-SHA256(salt, ikm) (RFC 5869 sec 2.2).
proto_bool	protocore_hkdf_expand (uint8_t *work, const uint8_t *prk, const uint8_t *info, size_t info_len, uint8_t *out, size_t out_len)
	OKM = T(1) | T(2) | ..., info taken verbatim (RFC 5869 sec 2.3).
proto_bool	protocore_hkdf_expand_label (uint8_t *work, const uint8_t *secret, const char *label, uint8_t *out, size_t out_len, const char *label_prefix)
	Expand under an HkdfLabel with an empty context.
proto_bool	protocore_hkdf_expand_label_ctx (uint8_t *work, const uint8_t *secret, const char *label, const uint8_t *context, size_t context_len, uint8_t *out, size_t out_len, const char *label_prefix)
	Expand under an HkdfLabel carrying a context, the Derive-Secret form.

Variables
PROTOCORE_NS HkdfNs Hkdf	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

HKDF-SHA256 (RFC 5869) and TLS 1.3 HKDF-Expand-Label (RFC 8446 sec 7.1).

QUIC packet protection keys are derived with the TLS 1.3 key schedule (RFC 9001 sec 5.2): an Initial secret is HKDF-Extract'd from a fixed salt and the client's Destination Connection ID, and every packet-protection value (key / iv / hp) is an HKDF-Expand-Label of a traffic secret. This is the same HMAC-SHA256 the SSH transport already ships, so these entries are a thin layer over the HmacSha256Ns entries rather than a second HMAC.

Pure, zero heap, host-tested against the RFC 9001 Appendix A worked examples (the HkdfLabel byte strings and the derived client/server secrets).

HkdfNs::expand caps out_len at 255*PROTOCORE_HKDF_HASH_LEN, the point past which the single-octet block counter has no encoding: out is zeroed and HkdfNs::ok comes back false.

work is PROTOCORE_HKDF_BORROW secure bytes the CALLER took, at an address it knows. It is not held past the call, so nothing here aliases it. The caller releases it, and the pool wipes on release; this module neither takes it, holds it, releases it, nor wipes it. The borrow carries the PRK and the T(i) block, so two derivations in flight are two borrows and never collide.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file hkdf.h.

Macro Definition Documentation

PROTOCORE_HKDF_HASH_LEN

#define PROTOCORE_HKDF_HASH_LEN   32

HKDF-SHA256 output block length (== SHA-256 digest length).

Definition at line 37 of file hkdf.h.

PROTOCORE_HKDF_LABEL_PREFIX

#define PROTOCORE_HKDF_LABEL_PREFIX   "tls13 "

The RFC 8446 sec 7.1 HKDF-Expand-Label prefix used by TLS 1.3 and QUIC. DTLS 1.3 overrides it with "dtls13" (RFC 9147 sec 5.9); callers that need it pass it explicitly.

Definition at line 41 of file hkdf.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	HkdfNs	,
		extract	,
		expand	,
		expand_label	,
		expand_label_ctx
	)

protocore_hkdf_extract()

proto_bool protocore_hkdf_extract	(	uint8_t *	work,
		const uint8_t *	salt,
		size_t	salt_len,
		const uint8_t *	ikm,
		size_t	ikm_len,
		uint8_t *	prk
	)

PRK = HMAC-SHA256(salt, ikm) (RFC 5869 sec 2.2).

Parameters

work	PROTOCORE_HKDF_BORROW bytes the caller took. Not held past the call.
salt	salt bytes; NULL only when salt_len is 0
salt_len	salt length
ikm	input keying material
ikm_len	its length
prk	PROTOCORE_HKDF_HASH_LEN bytes

Returns

PROTO_TRUE on success.

protocore_hkdf_expand()

proto_bool protocore_hkdf_expand	(	uint8_t *	work,
		const uint8_t *	prk,
		const uint8_t *	info,
		size_t	info_len,
		uint8_t *	out,
		size_t	out_len
	)

OKM = T(1) | T(2) | ..., info taken verbatim (RFC 5869 sec 2.3).

Parameters

work	PROTOCORE_HKDF_BORROW bytes the caller took. Not held past the call.
prk	PROTOCORE_HKDF_HASH_LEN bytes from extract
info	context taken verbatim; NULL only when info_len is 0
info_len	its length
out	output keying material
out_len	bytes requested; past 255*PROTOCORE_HKDF_HASH_LEN out is zeroed instead

Returns

PROTO_TRUE on success.

protocore_hkdf_expand_label()

proto_bool protocore_hkdf_expand_label	(	uint8_t *	work,
		const uint8_t *	secret,
		const char *	label,
		uint8_t *	out,
		size_t	out_len,
		const char *	label_prefix
	)

Expand under an HkdfLabel with an empty context.

Parameters

work	PROTOCORE_HKDF_BORROW bytes the caller took. Not held past the call.
secret	traffic secret (HKDF PRK), PROTOCORE_HKDF_HASH_LEN bytes
label	ASCII label without the prefix, <= 249 bytes
out	output keying material
out_len	bytes requested
label_prefix	PROTOCORE_HKDF_LABEL_PREFIX, or "dtls13" for DTLS 1.3

Returns

PROTO_TRUE on success.

protocore_hkdf_expand_label_ctx()

proto_bool protocore_hkdf_expand_label_ctx	(	uint8_t *	work,
		const uint8_t *	secret,
		const char *	label,
		const uint8_t *	context,
		size_t	context_len,
		uint8_t *	out,
		size_t	out_len,
		const char *	label_prefix
	)

Expand under an HkdfLabel carrying a context, the Derive-Secret form.

Parameters

work	PROTOCORE_HKDF_BORROW bytes the caller took. Not held past the call.
secret	PRK, PROTOCORE_HKDF_HASH_LEN bytes
label	ASCII label without the prefix, <= 249 bytes
context	context bytes, <= 255; NULL only when context_len is 0
context_len	context length
out	output keying material
out_len	bytes requested
label_prefix	PROTOCORE_HKDF_LABEL_PREFIX, or "dtls13" for DTLS 1.3

Returns

PROTO_TRUE on success.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS HkdfNs Hkdf PROTOCORE_UNUSED

Initial value:

= {.extract = protocore_hkdf_extract,
                                             .expand = protocore_hkdf_expand,
                                             .expand_label = protocore_hkdf_expand_label,
                                             .expand_label_ctx = protocore_hkdf_expand_label_ctx}

Module namespace.

Definition at line 107 of file hkdf.h.