keyschedule.h File Reference

RFC 8446 7.1: order-driven key schedule. More...

#include "common/bytes/span/span.h"
#include "tls/handshake/core/tls/initial.h"

Go to the source code of this file.

Data Structures
struct	quic_keysched
	Key schedule state: the current stage, the Master Secret once reached, and the four traffic key sets indexed by the QUIC_KS_* constants. More...

Enumerations
enum	{ QUIC_KS_CLIENT_HS = 0 , QUIC_KS_SERVER_HS = 1 , QUIC_KS_CLIENT_AP = 2 , QUIC_KS_SERVER_AP = 3 }
	which: handshake/application packet-protection keys per direction. More...

Functions
void	quic_keysched_init (quic_keysched *st)
	Enter the Early Secret stage.
void	quic_keysched_set_suite (quic_keysched *st, u16 suite)
	Override the cipher suite advance_handshake/advance_master derive Handshake/1-RTT keys for (RFC 8446 B.4).
int	quic_keysched_advance_handshake (quic_keysched *st, quic_span ecdhe, quic_span transcript)
	ServerHello received: derive Handshake Secret from the ECDHE shared secret and the client/server handshake traffic keys over the transcript.
int	quic_keysched_advance_handshake_psk (quic_keysched *st, quic_span psk, quic_span ecdhe, quic_span transcript)
	Same as quic_keysched_advance_handshake, but for a PSK-resumption handshake (RFC 8446 7.1's key schedule diagram): Handshake Secret is derived from Early Secret = HKDF-Extract(0, PSK) instead of HKDF-Extract(0, 0), matching quic_tls_handshake_secret_psk.
int	quic_keysched_advance_master (quic_keysched *st, const u8 *transcript, usz transcript_len)
	Finished processed: derive Master Secret and the application traffic keys.
int	quic_keysched_get (const quic_keysched *st, int which, const quic_initial_keys **out)
	If the keys for which have been derived, point *out at them and return 1; otherwise return 0.
int	quic_keysched_client_ap_secret (const quic_keysched *st, const u8 **out)
	The retained client_application_traffic_secret_0, valid once stage 2 is reached (same guard as quic_keysched_get with QUIC_KS_CLIENT_AP).
int	quic_keysched_server_ap_secret (const quic_keysched *st, const u8 **out)
	The retained server_application_traffic_secret_0, valid once stage 2 is reached.
int	quic_keysched_exporter_secret (const quic_keysched *st, const u8 **out)
	The retained exporter_master_secret (RFC 8446 7.1/7.5), valid once stage 2 is reached (same guard as quic_keysched_get with QUIC_KS_CLIENT_AP).

Detailed Description

RFC 8446 7.1: order-driven key schedule.

Drives the existing secret/key derivations in lock-step with handshake progress: Early -> Handshake (mix in ECDHE) -> Master, each stage producing traffic keys. Out-of-order advances are rejected.

Enumeration Type Documentation

anonymous enum

anonymous enum

which: handshake/application packet-protection keys per direction.

Enumerator
QUIC_KS_CLIENT_HS	client handshake traffic keys
QUIC_KS_SERVER_HS	server handshake traffic keys
QUIC_KS_CLIENT_AP	client application (1-RTT) traffic keys
QUIC_KS_SERVER_AP	server application (1-RTT) traffic keys

Function Documentation

quic_keysched_advance_handshake()

int quic_keysched_advance_handshake	(	quic_keysched *	st,
		quic_span	ecdhe,
		quic_span	transcript )

ServerHello received: derive Handshake Secret from the ECDHE shared secret and the client/server handshake traffic keys over the transcript.

Parameters

st	schedule state (must be in the init stage)
ecdhe	ECDHE shared secret
transcript	raw transcript bytes (ClientHello..ServerHello), hashed internally

Returns

1 on success, 0 if the stage is not init (order violation).

quic_keysched_advance_handshake_psk()

int quic_keysched_advance_handshake_psk	(	quic_keysched *	st,
		quic_span	psk,
		quic_span	ecdhe,
		quic_span	transcript )

Same as quic_keysched_advance_handshake, but for a PSK-resumption handshake (RFC 8446 7.1's key schedule diagram): Handshake Secret is derived from Early Secret = HKDF-Extract(0, PSK) instead of HKDF-Extract(0, 0), matching quic_tls_handshake_secret_psk.

ECDHE is still mixed in either way – this SDK never runs PSK-only (no (EC)DHE).

Parameters

st	schedule state (must be in the init stage)
psk	the accepted ticket's resumption secret (QUIC_HKDF_PRK bytes)
ecdhe	ECDHE shared secret
transcript	raw transcript bytes (ClientHello..ServerHello), hashed internally

Returns

1 on success, 0 if the stage is not init (order violation).

quic_keysched_advance_master()

int quic_keysched_advance_master	(	quic_keysched *	st,
		const u8 *	transcript,
		usz	transcript_len )

Finished processed: derive Master Secret and the application traffic keys.

Parameters

st	schedule state (must be in the handshake stage)
transcript	raw transcript bytes (ClientHello..server Finished), hashed internally
transcript_len	number of bytes at transcript

Returns

1 on success, 0 if the stage is not handshake (order violation).

quic_keysched_client_ap_secret()

int quic_keysched_client_ap_secret	(	const quic_keysched *	st,
		const u8 **	out )

The retained client_application_traffic_secret_0, valid once stage 2 is reached (same guard as quic_keysched_get with QUIC_KS_CLIENT_AP).

Parameters

st	schedule state to query
out	receives a pointer to the QUIC_HKDF_PRK-byte secret

Returns

1 if derived, 0 otherwise.

quic_keysched_exporter_secret()

int quic_keysched_exporter_secret	(	const quic_keysched *	st,
		const u8 **	out )

The retained exporter_master_secret (RFC 8446 7.1/7.5), valid once stage 2 is reached (same guard as quic_keysched_get with QUIC_KS_CLIENT_AP).

Feed *out into quic_tls_exporter (exporter.h) to compute a TLS-Exporter value.

Parameters

st	schedule state to query
out	receives a pointer to the QUIC_HKDF_PRK-byte secret

Returns

1 if derived, 0 otherwise.

quic_keysched_get()

int quic_keysched_get	(	const quic_keysched *	st,
		int	which,
		const quic_initial_keys **	out )

If the keys for which have been derived, point *out at them and return 1; otherwise return 0.

*out points into st and stays valid while st lives.

Parameters

st	schedule state to query
which	key selector (QUIC_KS_*)
out	receives a pointer to the derived keys

Returns

1 if derived, 0 otherwise.

quic_keysched_init()

void quic_keysched_init

(

quic_keysched *

st

)

Enter the Early Secret stage.

Parameters

st	schedule state to initialize

quic_keysched_server_ap_secret()

int quic_keysched_server_ap_secret	(	const quic_keysched *	st,
		const u8 **	out )

The retained server_application_traffic_secret_0, valid once stage 2 is reached.

Same shape as quic_keysched_client_ap_secret, for the send side.

Parameters

st	schedule state to query
out	receives a pointer to the QUIC_HKDF_PRK-byte secret

Returns

1 if derived, 0 otherwise.

quic_keysched_set_suite()

void quic_keysched_set_suite	(	quic_keysched *	st,
		u16	suite )

Override the cipher suite advance_handshake/advance_master derive Handshake/1-RTT keys for (RFC 8446 B.4).

Call before advance_handshake; quic_keysched_init already set the AES_128_GCM_SHA256 default, so callers that never negotiate ChaCha20 need not call this at all.

Parameters

st	schedule state to configure
suite	negotiated TLS 1.3 cipher suite code point