quic_crypto.h File Reference

QUIC packet protection: Initial secrets, AEAD payload protection, header protection, and the Retry integrity tag (RFC 9001). More...

#include "crypto/kdf/hkdf/hkdf.h"
#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	QuicPacketKeys
	The client/server packet-protection secrets for one QUIC encryption level. More...
struct	QuicInitialSecrets
	Both directions' Initial secrets derived from the client's Destination Connection ID. More...
struct	QuicCryptoNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Functions
	PROTOCORE_NS_LAYOUT (QuicCryptoNs, derive_initial_secrets, keys_from_secret, packet_protect, packet_unprotect, retry_integrity_tag)
void	protocore_quic_crypto_derive_initial_secrets (uint8_t *work, uint8_t *keys_work, const uint8_t *dcid, size_t dcid_len, QuicInitialSecrets *out)
	Derive the Initial packet-protection secrets (RFC 9001 sec 5.2). .
void	protocore_quic_crypto_keys_from_secret (uint8_t *work, uint8_t *keys_work, const uint8_t *secret, QuicPacketKeys *out)
	Expand one traffic secret into a {key, iv, hp} triple (RFC 9001 sec .
size_t	protocore_quic_crypto_packet_protect (uint8_t *work, uint8_t *pkt, size_t cap, size_t pn_offset, uint8_t pn_len, uint64_t full_pn, size_t payload_len, QuicPacketKeys *keys, proto_bool is_long)
	Protect one QUIC packet in place: AEAD-seal the payload, then apply .
size_t	protocore_quic_crypto_packet_unprotect (uint8_t *work, uint8_t *pkt, size_t pn_offset, size_t length, uint64_t largest_pn, QuicPacketKeys *keys, proto_bool is_long, uint8_t *out, uint64_t *out_pn)
	Remove header protection and AEAD-open one QUIC packet in place .
void	protocore_quic_crypto_retry_integrity_tag (uint8_t *work, const uint8_t *odcid, size_t odcid_len, const uint8_t *retry, size_t retry_len, uint8_t *tag)
	Compute the Retry Integrity Tag (RFC 9001 sec 5.8). .

Variables
PROTOCORE_NS QuicCryptoNs QuicCrypto	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

QUIC packet protection: Initial secrets, AEAD payload protection, header protection, and the Retry integrity tag (RFC 9001).

This ties the HKDF key schedule (protocore_hkdf) and AEAD_AES_128_GCM (aes128gcm) into the two QUIC packet-protection operations of RFC 9001 sec 5:

• QuicCrypto.derive_initial_secrets runs the sec 5.2 Initial key derivation: a fixed salt and the client's Destination Connection ID produce the client and server {key, iv, hp} triples that protect Initial packets (the only keys available before the TLS handshake yields more).
• QuicCrypto.packet_protect / QuicCrypto.packet_unprotect perform sec 5.3 AEAD payload protection and sec 5.4 header protection together, on a whole packet in a buffer. They take a {key, iv, hp} triple and a header form, so the same code protects Initial, Handshake, and 1-RTT packets - only the secrets differ. AES-128-GCM header protection samples a 16-byte AES-ECB block.
• QuicCrypto.retry_integrity_tag computes the sec 5.8 Retry Integrity Tag (a fixed-key AEAD over the Retry Pseudo-Packet).

Pure, zero heap, host-tested against RFC 9001 Appendix A (client Initial A.2, server Initial A.3, Retry A.4).

work is bytes the CALLER holds. This module reads none of them: it carries nothing between calls, so there is no state to keep and nothing to wipe. The parameter is there so a caller drives every namespace the same way.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file quic_crypto.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	QuicCryptoNs	,
		derive_initial_secrets	,
		keys_from_secret	,
		packet_protect	,
		packet_unprotect	,
		retry_integrity_tag
	)

protocore_quic_crypto_derive_initial_secrets()

void protocore_quic_crypto_derive_initial_secrets	(	uint8_t *	work,
		uint8_t *	keys_work,
		const uint8_t *	dcid,
		size_t	dcid_len,
		QuicInitialSecrets *	out
	)

Derive the Initial packet-protection secrets (RFC 9001 sec 5.2). .

Parameters

work	PROTOCORE_QUIC_CRYPTO_BORROW bytes the caller took. Not held past the call.
keys_work	Keys work
dcid	Dcid
dcid_len	Dcid len
out	Out

protocore_quic_crypto_keys_from_secret()

void protocore_quic_crypto_keys_from_secret	(	uint8_t *	work,
		uint8_t *	keys_work,
		const uint8_t *	secret,
		QuicPacketKeys *	out
	)

Expand one traffic secret into a {key, iv, hp} triple (RFC 9001 sec .

Parameters

work	PROTOCORE_QUIC_CRYPTO_BORROW bytes the caller took. Not held past the call.
keys_work	Keys work
secret	PROTOCORE_HKDF_HASH_LEN bytes
out	Out

protocore_quic_crypto_packet_protect()

size_t protocore_quic_crypto_packet_protect	(	uint8_t *	work,
		uint8_t *	pkt,
		size_t	cap,
		size_t	pn_offset,
		uint8_t	pn_len,
		uint64_t	full_pn,
		size_t	payload_len,
		QuicPacketKeys *	keys,
		proto_bool	is_long
	)

Protect one QUIC packet in place: AEAD-seal the payload, then apply .

Parameters

work	PROTOCORE_QUIC_CRYPTO_BORROW bytes the caller took. Not held past the call.
pkt	Buffer holding header || plaintext payload; rewritten to header || ciphertext
cap	Capacity of pkt; must be >= pn_offset + pn_len + payload_len + 16
pn_offset	Offset of the packet number within the header
pn_len	Packet-number length in bytes (1..4)
full_pn	Full (untruncated) packet number, for the AEAD nonce
payload_len	Plaintext payload length in bytes
keys	The {key, iv, hp} triple for this encryption level
is_long	True for a long header (Initial/Handshake), false for a 1-RTT short header

Returns

The size_t.

protocore_quic_crypto_packet_unprotect()

size_t protocore_quic_crypto_packet_unprotect	(	uint8_t *	work,
		uint8_t *	pkt,
		size_t	pn_offset,
		size_t	length,
		uint64_t	largest_pn,
		QuicPacketKeys *	keys,
		proto_bool	is_long,
		uint8_t *	out,
		uint64_t *	out_pn
	)

Remove header protection and AEAD-open one QUIC packet in place .

Parameters

work	PROTOCORE_QUIC_CRYPTO_BORROW bytes the caller took. Not held past the call.
pkt	Buffer holding the protected packet (mutated: header unprotected in place)
pn_offset	Offset of the protected packet number
length	QUIC Length field (packet-number + payload + tag bytes)
largest_pn	Largest packet number already received at this level (0 if none yet)
keys	The {key, iv, hp} triple for this encryption level
is_long	True for a long header, false for a 1-RTT short header
out	Output plaintext frames (>= length - pn_len - 16 bytes); may alias pkt payload
out_pn	Receives the reconstructed full packet number (may be NULL)

Returns

The size_t.

protocore_quic_crypto_retry_integrity_tag()

void protocore_quic_crypto_retry_integrity_tag	(	uint8_t *	work,
		const uint8_t *	odcid,
		size_t	odcid_len,
		const uint8_t *	retry,
		size_t	retry_len,
		uint8_t *	tag
	)

Compute the Retry Integrity Tag (RFC 9001 sec 5.8). .

Parameters

work	PROTOCORE_QUIC_CRYPTO_BORROW bytes the caller took. Not held past the call.
odcid	Original Destination Connection ID (from the client's first Initial)
odcid_len	ODCID length in bytes
retry	Retry packet bytes from the first byte up to (not including) the tag
retry_len	Length of retry
tag	Output 16-byte integrity tag 16 bytes

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS QuicCryptoNs QuicCrypto PROTOCORE_UNUSED

Initial value:

= {
    .derive_initial_secrets = protocore_quic_crypto_derive_initial_secrets,
    .keys_from_secret = protocore_quic_crypto_keys_from_secret,
    .packet_protect = protocore_quic_crypto_packet_protect,
    .packet_unprotect = protocore_quic_crypto_packet_unprotect,
    .retry_integrity_tag = protocore_quic_crypto_retry_integrity_tag}

Module namespace.

Definition at line 140 of file quic_crypto.h.