quic_packet.h File Reference

QUIC packet headers and packet-number coding (RFC 9000 sec 17). More...

#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	QuicLongHeader
	A parsed long header (invariant fields). A Version of 0 marks a Version Negotiation. More...
struct	QuicShortHeader
	A parsed short header (1-RTT). The DCID length is known locally, not on the wire. More...
struct	QuicPacketNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Macros
#define	QUIC_VERSION_1   0x00000001u
	RFC 9000.
#define	QUIC_MAX_CID_LEN   20
	maximum connection-ID length in QUIC version 1
#define	QUIC_LP_INITIAL   0x00
	Long-header packet types (RFC 9000 sec 17.2, Table 5).
#define	QUIC_LP_0RTT   0x01
#define	QUIC_LP_HANDSHAKE   0x02
#define	QUIC_LP_RETRY   0x03

Functions
	PROTOCORE_NS_LAYOUT (QuicPacketNs, is_long_header, parse_long_header, build_long_header, parse_short_header, build_version_negotiation, pn_length, pn_encode, pn_decode)
proto_bool	protocore_quic_packet_is_long_header (uint8_t *work, uint8_t first)
	True if byte 0 selects the long header form (0x80 set).
proto_bool	protocore_quic_packet_parse_long_header (uint8_t *work, const uint8_t *buf, size_t len, QuicLongHeader *out)
	Parse a long header. false if truncated or a connection ID exceeds .
size_t	protocore_quic_packet_build_long_header (uint8_t *work, uint8_t *out, size_t cap, uint8_t type, uint32_t version, const uint8_t *dcid, uint8_t dcid_len, const uint8_t *scid, uint8_t scid_len, uint8_t pn_len)
	Build a long header's invariant fields (first byte .. Source .
proto_bool	protocore_quic_packet_parse_short_header (uint8_t *work, const uint8_t *buf, size_t len, uint8_t dcid_len, QuicShortHeader *out)
	Parse a short (1-RTT) header given the locally chosen dcid_len. .
size_t	protocore_quic_packet_build_version_negotiation (uint8_t *work, uint8_t *out, size_t cap, const uint8_t *dcid, uint8_t dcid_len, const uint8_t *scid, uint8_t scid_len, const uint32_t *versions, size_t nversions)
	Build a Version Negotiation packet (RFC 9000 sec 17.2.1): Version 0 .
uint8_t	protocore_quic_packet_pn_length (uint8_t *work, uint64_t full_pn, int64_t largest_acked)
	Packet-number length in bytes (1..4) for full_pn; largest_acked < 0 .
size_t	protocore_quic_packet_pn_encode (uint8_t *work, uint8_t *out, size_t cap, uint64_t full_pn, int64_t largest_acked)
	Encode full_pn truncated to QuicPacketNs::pn_length bytes, .
uint64_t	protocore_quic_packet_pn_decode (uint8_t *work, uint64_t largest_pn, uint64_t truncated_pn, uint8_t pn_nbits)
	Recover the full packet number from a truncated_pn of pn_nbits bits .

Variables
PROTOCORE_NS QuicPacketNs QuicPacket	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

QUIC packet headers and packet-number coding (RFC 9000 sec 17).

The structural, version-independent layer of a QUIC packet: the long-header form (Initial / 0-RTT / Handshake / Retry, plus the Version Negotiation packet whose Version is 0) and the short-header 1-RTT form, and the packet-number truncation coding (sec 17.1, Appendix A.2/A.3).

This is the unprotected structure only - it parses and builds the header fields that are not covered by header protection (header form, version, connection IDs) and codes packet numbers. Packet protection (AEAD) and header protection are layered on top by the QUIC crypto module. Pure, zero heap, host-tested against the RFC worked examples.

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

Macro Definition Documentation

QUIC_VERSION_1

#define QUIC_VERSION_1   0x00000001u

RFC 9000.

Definition at line 36 of file quic_packet.h.

QUIC_MAX_CID_LEN

#define QUIC_MAX_CID_LEN   20

maximum connection-ID length in QUIC version 1

Definition at line 37 of file quic_packet.h.

QUIC_LP_INITIAL

#define QUIC_LP_INITIAL   0x00

Long-header packet types (RFC 9000 sec 17.2, Table 5).

Definition at line 40 of file quic_packet.h.

QUIC_LP_0RTT

#define QUIC_LP_0RTT   0x01

Definition at line 41 of file quic_packet.h.

QUIC_LP_HANDSHAKE

#define QUIC_LP_HANDSHAKE   0x02

Definition at line 42 of file quic_packet.h.

QUIC_LP_RETRY

#define QUIC_LP_RETRY   0x03

Definition at line 43 of file quic_packet.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	QuicPacketNs	,
		is_long_header	,
		parse_long_header	,
		build_long_header	,
		parse_short_header	,
		build_version_negotiation	,
		pn_length	,
		pn_encode	,
		pn_decode
	)

protocore_quic_packet_is_long_header()

proto_bool protocore_quic_packet_is_long_header	(	uint8_t *	work,
		uint8_t	first
	)

True if byte 0 selects the long header form (0x80 set).

Parameters

work	PROTOCORE_QUIC_PACKET_BORROW bytes the caller took. Not held past the call.
first	First

Returns

PROTO_TRUE on success.

protocore_quic_packet_parse_long_header()

proto_bool protocore_quic_packet_parse_long_header	(	uint8_t *	work,
		const uint8_t *	buf,
		size_t	len,
		QuicLongHeader *	out
	)

Parse a long header. false if truncated or a connection ID exceeds .

Parameters

work	PROTOCORE_QUIC_PACKET_BORROW bytes the caller took. Not held past the call.
buf	Buf
len	Len
out	Out

Returns

PROTO_TRUE on success.

protocore_quic_packet_build_long_header()

size_t protocore_quic_packet_build_long_header	(	uint8_t *	work,
		uint8_t *	out,
		size_t	cap,
		uint8_t	type,
		uint32_t	version,
		const uint8_t *	dcid,
		uint8_t	dcid_len,
		const uint8_t *	scid,
		uint8_t	scid_len,
		uint8_t	pn_len
	)

Build a long header's invariant fields (first byte .. Source .

Parameters

work	PROTOCORE_QUIC_PACKET_BORROW bytes the caller took. Not held past the call.
out	Out
cap	Cap
type	Type
version	Version
dcid	Dcid
dcid_len	Dcid len
scid	Scid
scid_len	Scid len
pn_len	Pn len

Returns

The size_t.

protocore_quic_packet_parse_short_header()

proto_bool protocore_quic_packet_parse_short_header	(	uint8_t *	work,
		const uint8_t *	buf,
		size_t	len,
		uint8_t	dcid_len,
		QuicShortHeader *	out
	)

Parse a short (1-RTT) header given the locally chosen dcid_len. .

Parameters

work	PROTOCORE_QUIC_PACKET_BORROW bytes the caller took. Not held past the call.
buf	Buf
len	Len
dcid_len	Dcid len
out	Out

Returns

PROTO_TRUE on success.

protocore_quic_packet_build_version_negotiation()

size_t protocore_quic_packet_build_version_negotiation	(	uint8_t *	work,
		uint8_t *	out,
		size_t	cap,
		const uint8_t *	dcid,
		uint8_t	dcid_len,
		const uint8_t *	scid,
		uint8_t	scid_len,
		const uint32_t *	versions,
		size_t	nversions
	)

Build a Version Negotiation packet (RFC 9000 sec 17.2.1): Version 0 .

Parameters

work	PROTOCORE_QUIC_PACKET_BORROW bytes the caller took. Not held past the call.
out	Out
cap	Cap
dcid	Dcid
dcid_len	Dcid len
scid	Scid
scid_len	Scid len
versions	Versions
nversions	Nversions

Returns

The size_t.

protocore_quic_packet_pn_length()

uint8_t protocore_quic_packet_pn_length	(	uint8_t *	work,
		uint64_t	full_pn,
		int64_t	largest_acked
	)

Packet-number length in bytes (1..4) for full_pn; largest_acked < 0 .

Parameters

work	PROTOCORE_QUIC_PACKET_BORROW bytes the caller took. Not held past the call.
full_pn	Full pn
largest_acked	Largest acked

Returns

The uint8_t.

protocore_quic_packet_pn_encode()

size_t protocore_quic_packet_pn_encode	(	uint8_t *	work,
		uint8_t *	out,
		size_t	cap,
		uint64_t	full_pn,
		int64_t	largest_acked
	)

Encode full_pn truncated to QuicPacketNs::pn_length bytes, .

Parameters

work	PROTOCORE_QUIC_PACKET_BORROW bytes the caller took. Not held past the call.
out	Out
cap	Cap
full_pn	Full pn
largest_acked	Largest acked

Returns

The size_t.

protocore_quic_packet_pn_decode()

uint64_t protocore_quic_packet_pn_decode	(	uint8_t *	work,
		uint64_t	largest_pn,
		uint64_t	truncated_pn,
		uint8_t	pn_nbits
	)

Recover the full packet number from a truncated_pn of pn_nbits bits .

Parameters

work	PROTOCORE_QUIC_PACKET_BORROW bytes the caller took. Not held past the call.
largest_pn	Largest pn
truncated_pn	Truncated pn
pn_nbits	Pn nbits

Returns

The uint64_t.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS QuicPacketNs QuicPacket PROTOCORE_UNUSED

Initial value:

= {.is_long_header = protocore_quic_packet_is_long_header,
                                                         .parse_long_header = protocore_quic_packet_parse_long_header,
                                                         .build_long_header = protocore_quic_packet_build_long_header,
                                                         .parse_short_header = protocore_quic_packet_parse_short_header,
                                                         .build_version_negotiation =
                                                             protocore_quic_packet_build_version_negotiation,
                                                         .pn_length = protocore_quic_packet_pn_length,
                                                         .pn_encode = protocore_quic_packet_pn_encode,
                                                         .pn_decode = protocore_quic_packet_pn_decode}

Module namespace.

Definition at line 177 of file quic_packet.h.