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"
#include "tls/handshake/core/tls/suitehash.h"

Go to the source code of this file.

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

Enumerations
enum	{ KS_CLIENT_HS = 0 , KS_SERVER_HS = 1 , KS_CLIENT_AP = 2 , KS_SERVER_AP = 3 }
	which: handshake/application packet-protection keys per direction. More...

Functions
void	keysched_init (keysched *st)
	Enter the Early Secret stage.
void	keysched_set_suite (keysched *st, u16 suite)
	Override the cipher suite advance_handshake/advance_master derive Handshake/1-RTT keys for (RFC 8446 B.4).
void	keysched_set_version (keysched *st, u32 version)
	Override the QUIC version whose label prefix advance_handshake/ advance_master derive Handshake/1-RTT packet-protection keys with (RFC 9369 3.3.1).
int	keysched_advance_handshake (keysched *st, wired_span ecdhe, wired_span transcript)
	ServerHello received: derive Handshake Secret from the ECDHE shared secret and the client/server handshake traffic keys over the transcript.
int	keysched_advance_handshake_psk (keysched *st, wired_span psk, wired_span ecdhe, wired_span transcript)
	Same as 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 tls_handshake_secret_psk.
int	keysched_advance_master (keysched *st, const u8 *transcript, usz transcript_len)
	Finished processed: derive Master Secret and the application traffic keys.
int	keysched_get (const keysched *st, int which, const initial_keys **out)
	If the keys for which have been derived, point *out at them and return 1; otherwise return 0.
int	keysched_client_ap_secret (const keysched *st, const u8 **out)
	The retained client_application_traffic_secret_0, valid once stage 2 is reached (same guard as keysched_get with KS_CLIENT_AP).
int	keysched_server_ap_secret (const keysched *st, const u8 **out)
	The retained server_application_traffic_secret_0, valid once stage 2 is reached.
int	keysched_exporter_secret (const 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 keysched_get with KS_CLIENT_AP).
void	keysched_wipe (keysched *st)
	RFC 8446 E.1.4 / 7.5: erase every retained secret (Master Secret, the traffic secrets and keys, exporter_master_secret) and return the schedule to stage 0, so a torn-down connection leaves no exporter or traffic material behind.

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
KS_CLIENT_HS	client handshake traffic keys
KS_SERVER_HS	server handshake traffic keys
KS_CLIENT_AP	client application (1-RTT) traffic keys
KS_SERVER_AP	server application (1-RTT) traffic keys

Function Documentation

keysched_advance_handshake()

int keysched_advance_handshake	(	keysched *	st,
		wired_span	ecdhe,
		wired_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).

keysched_advance_handshake_psk()

int keysched_advance_handshake_psk	(	keysched *	st,
		wired_span	psk,
		wired_span	ecdhe,
		wired_span	transcript )

Same as 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 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 (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).

keysched_advance_master()

int keysched_advance_master	(	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).

keysched_client_ap_secret()

int keysched_client_ap_secret	(	const keysched *	st,
		const u8 **	out )

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

Parameters

st	schedule state to query
out	receives a pointer to the Hash.length-byte secret (the suite's, see tls_hash_of)

Returns

1 if derived, 0 otherwise.

keysched_exporter_secret()

int keysched_exporter_secret	(	const 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 keysched_get with KS_CLIENT_AP).

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

Parameters

st	schedule state to query
out	receives a pointer to the Hash.length-byte secret (the suite's, see tls_hash_of)

Returns

1 if derived, 0 otherwise.

keysched_get()

int keysched_get	(	const keysched *	st,
		int	which,
		const 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 (KS_*)
out	receives a pointer to the derived keys

Returns

1 if derived, 0 otherwise.

keysched_init()

void keysched_init

(

keysched *

st

)

Enter the Early Secret stage.

Parameters

st	schedule state to initialize

keysched_server_ap_secret()

int keysched_server_ap_secret	(	const keysched *	st,
		const u8 **	out )

The retained server_application_traffic_secret_0, valid once stage 2 is reached.

Same shape as keysched_client_ap_secret, for the send side.

Parameters

st	schedule state to query
out	receives a pointer to the Hash.length-byte secret (the suite's, see tls_hash_of)

Returns

1 if derived, 0 otherwise.

keysched_set_suite()

void keysched_set_suite	(	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; 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

keysched_set_version()

void keysched_set_version	(	keysched *	st,
		u32	version )

Override the QUIC version whose label prefix advance_handshake/ advance_master derive Handshake/1-RTT packet-protection keys with (RFC 9369 3.3.1).

Call before advance_handshake; keysched_init already set the VERSION_1 default, so v1-only callers need not call this at all.

Parameters

st	schedule state to configure
version	negotiated QUIC version (VERSION_1 or VERSION_2)

keysched_wipe()

void keysched_wipe

(

keysched *

st

)

RFC 8446 E.1.4 / 7.5: erase every retained secret (Master Secret, the traffic secrets and keys, exporter_master_secret) and return the schedule to stage 0, so a torn-down connection leaves no exporter or traffic material behind.

The accessors report nothing available afterwards.

Parameters

st	the schedule to wipe