TLS 1.3 key schedule, HKDF label derivation, traffic-secret expansion, Finished verification, CertificateVerify input construction, and PSK binder derivation. More...

#include "qsccommon.h"
#include "tlserrors.h"
#include "tlstypes.h"
#include "tlsstate.h"

Data Structures
struct	qsc_tls_key_schedule_state
	TLS 1.3 key schedule state and derived secret container. More...

Typedefs
typedef struct qsc_tls_key_schedule_state	qsc_tls_key_schedule_state

Functions
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_state_initialize (qsc_tls_key_schedule_state *state, qsc_tls_hash_algorithm hash)
	Initialize a TLS key schedule state.
QSC_EXPORT_API void	qsc_tls_keyschedule_state_dispose (qsc_tls_key_schedule_state *state)
	Dispose of a TLS key schedule state.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_hkdf_extract (qsc_tls_hash_algorithm hash, const uint8_t salt, size_t saltlen, const uint8_t ikm, size_t ikmlen, uint8_t *output, size_t outlen)
	Perform HKDF-Extract for the selected TLS hash algorithm.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_hkdf_expand (qsc_tls_hash_algorithm hash, const uint8_t prk, size_t prklen, const uint8_t info, size_t infolen, uint8_t *output, size_t outlen)
	Perform HKDF-Expand for the selected TLS hash algorithm.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_hkdf_expand_label (qsc_tls_hash_algorithm hash, const uint8_t secret, size_t secretlen, const char label, size_t labellen, const uint8_t context, size_t contextlen, uint8_t output, size_t outlen)
	Perform TLS 1.3 HKDF-Expand-Label.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_derive_secret_with_hash (qsc_tls_hash_algorithm hash, const uint8_t secret, size_t secretlen, const char label, size_t labellen, const uint8_t transcripthash, size_t transcripthashlen, uint8_t output, size_t outlen)
	Derive a TLS 1.3 secret using a supplied transcript hash.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_derive_secret_empty (qsc_tls_hash_algorithm hash, const uint8_t secret, size_t secretlen, const char label, size_t labellen, uint8_t *output, size_t outlen)
	Derive a TLS 1.3 secret using the hash of the empty string.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_extract_early_secret (qsc_tls_key_schedule_state state, const uint8_t psk, size_t psklen)
	Extract the TLS 1.3 early secret.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_extract_handshake_secret (qsc_tls_key_schedule_state state, const uint8_t dhe, size_t dhelen)
	Extract the TLS 1.3 handshake secret.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_extract_master_secret (qsc_tls_key_schedule_state *state)
	Extract the TLS 1.3 master secret.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_derive_handshake_traffic_secrets (qsc_tls_key_schedule_state state, const uint8_t transcripthash, size_t transcripthashlen)
	Derive the client and server handshake traffic secrets.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_derive_application_traffic_secrets (qsc_tls_key_schedule_state state, const uint8_t transcripthash, size_t transcripthashlen)
	Derive the client and server application traffic secrets.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_derive_exporter_master_secret (qsc_tls_key_schedule_state state, const uint8_t transcripthash, size_t transcripthashlen)
	Derive the exporter master secret.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_derive_resumption_master_secret (qsc_tls_key_schedule_state state, const uint8_t transcripthash, size_t transcripthashlen)
	Derive the resumption master secret.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_derive_traffic_keys (qsc_tls_hash_algorithm hash, const uint8_t trafficsecret, size_t trafficsecretlen, size_t keylen, size_t ivlen, uint8_t keyoutput, uint8_t *ivoutput)
	Derive record protection key and IV material from a traffic secret.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_advance_traffic_secret (qsc_tls_hash_algorithm hash, const uint8_t currenttrafficsecret, size_t trafficsecretlen, uint8_t nexttrafficsecret)
	Advance an application traffic secret for TLS KeyUpdate.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_compute_finished (qsc_tls_hash_algorithm hash, const uint8_t basekey, size_t basekeylen, const uint8_t transcripthash, size_t transcripthashlen, uint8_t output, size_t outlen, size_t written)
	Compute a TLS 1.3 Finished verify_data value.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_verify_finished (qsc_tls_hash_algorithm hash, const uint8_t basekey, size_t basekeylen, const uint8_t transcripthash, size_t transcripthashlen, const uint8_t *candidate, size_t candidatelen)
	Verify a TLS 1.3 Finished verify_data value.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_build_certificate_verify_input (const char contextstring, const uint8_t transcripthash, size_t transcripthashlen, uint8_t output, size_t outlen, size_t written)
	Build the TLS 1.3 CertificateVerify signature input.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_suite_record_sizes (qsc_tls_cipher_suite suite, size_t keylen, size_t ivlen)
	Resolve record protection key and IV lengths for a TLS cipher suite.
QSC_EXPORT_API qsc_tls_hash_algorithm	qsc_tls_keyschedule_suite_hash (qsc_tls_cipher_suite suite)
	Resolve the hash algorithm associated with a TLS cipher suite.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_derive_resumption_psk (const qsc_tls_key_schedule_state state, const uint8_t nonce, size_t noncelen, uint8_t *output, size_t outlen)
	Derive a resumption PSK from the resumption master secret.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_derive_binder_key (qsc_tls_key_schedule_state *state, bool external)
	Derive the TLS 1.3 PSK binder key.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_derive_client_early_traffic_secret (qsc_tls_key_schedule_state state, const uint8_t transcripthash, size_t transcripthashlen)
	Derive the client early traffic secret for 0-RTT data.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_derive_early_exporter_secret (qsc_tls_key_schedule_state state, const uint8_t transcripthash, size_t transcripthashlen)
	Derive the early exporter master secret.
QSC_EXPORT_API qsc_tls_status	qsc_tls_keyschedule_compute_psk_binder (qsc_tls_hash_algorithm hash, const uint8_t binderkey, size_t binderkeylen, const uint8_t partialtranshash, size_t transcripthashlen, uint8_t output, size_t outlen, size_t written)
	Compute a TLS 1.3 PSK binder MAC.

Detailed Description

TLS 1.3 key schedule, HKDF label derivation, traffic-secret expansion, Finished verification, CertificateVerify input construction, and PSK binder derivation.

This header defines the QSC TLS 1.3 key schedule interface. The functions in this module implement the staged secret derivation chain used by the TLS 1.3 handshake, including the early secret, handshake secret, master secret, handshake traffic secrets, application traffic secrets, exporter master secret, resumption master secret, resumption PSK, 0-RTT early traffic secret, and PSK binder key.

The key schedule is parameterized by the negotiated TLS hash algorithm. It provides HKDF-Extract, HKDF-Expand, and HKDF-Expand-Label helpers for protocol code that must derive secrets using the TLS 1.3 label format. The module also provides utility functions for deriving record protection keys and IVs, advancing application traffic secrets during KeyUpdate, computing and verifying Finished MAC values, and constructing the context-bound input used by CertificateVerify signatures.

All secret material stored in qsc_tls_key_schedule_state is fixed-size and bounded by QSC_TLS_HASH_MAX_SIZE. Callers shall initialize a state object with qsc_tls_keyschedule_state_initialize() before use and dispose it with qsc_tls_keyschedule_state_dispose() when the handshake or connection state is no longer required.

Usage

Typical full handshake use follows this sequence:

qsc_tls_key_schedule_state ks;
qsc_tls_keyschedule_state_initialize(&ks, qsc_tls_hash_algorithm_sha256);
qsc_tls_keyschedule_extract_early_secret(&ks, NULL, 0U);
qsc_tls_keyschedule_extract_handshake_secret(&ks, shared_secret, shared_secret_len);
qsc_tls_keyschedule_derive_handshake_traffic_secrets(&ks, ch_sh_hash, hash_len);
qsc_tls_keyschedule_extract_master_secret(&ks);
qsc_tls_keyschedule_derive_application_traffic_secrets(&ks, sf_hash, hash_len);
qsc_tls_keyschedule_derive_exporter_master_secret(&ks, sf_hash, hash_len);
qsc_tls_keyschedule_derive_resumption_master_secret(&ks, cf_hash, hash_len);
qsc_tls_keyschedule_state_dispose(&ks);

Remarks: The module performs key schedule derivation only. It does not own transcript hash state, perform record encryption, or negotiate cipher suites. Transcript hashes must be supplied by the caller at the exact protocol boundary required by TLS 1.3.

Function Documentation

◆ qsc_tls_keyschedule_advance_traffic_secret()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_advance_traffic_secret	(	qsc_tls_hash_algorithm	hash,
		const uint8_t *	currenttrafficsecret,
		size_t	trafficsecretlen,
		uint8_t *	nexttrafficsecret )

Advance an application traffic secret for TLS KeyUpdate.

Computes the next traffic secret from the current traffic secret using the TLS 1.3 "traffic upd" label. The caller is responsible for replacing the active read or write traffic secret and deriving new record protection keys.

Parameters

hash	[qsc_tls_hash_algorithm] Hash algorithm selector.
currenttrafficsecret	[const uint8_t*] Pointer to the current traffic secret.
trafficsecretlen	[size_t] Length, in bytes, of the current traffic secret.
nexttrafficsecret	[uint8_t*] Pointer to the destination buffer for the next traffic secret.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_build_certificate_verify_input()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_build_certificate_verify_input	(	const char *	contextstring,
		const uint8_t *	transcripthash,
		size_t	transcripthashlen,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written )

Build the TLS 1.3 CertificateVerify signature input.

Constructs the exact CertificateVerify input defined by TLS 1.3: 64 space characters, followed by the role-specific context string, followed by a single zero byte separator, followed by the transcript hash. The resulting buffer is the message that is signed or verified by the certificate authentication layer.

Parameters

contextstring	[const char*] Pointer to the role-specific context string, for example "TLS 1.3, server CertificateVerify".
transcripthash	[const uint8_t*] Pointer to the transcript hash at the CertificateVerify boundary.
transcripthashlen	[size_t] Length, in bytes, of the transcript hash.
output	[uint8_t*] Pointer to the destination buffer.
outlen	[size_t] Length, in bytes, of the destination buffer.
written	[size_t*] Pointer receiving the number of bytes written.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_compute_finished()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_compute_finished	(	qsc_tls_hash_algorithm	hash,
		const uint8_t *	basekey,
		size_t	basekeylen,
		const uint8_t *	transcripthash,
		size_t	transcripthashlen,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written )

Compute a TLS 1.3 Finished verify_data value.

Derives finished_key from basekey using HKDF-Expand-Label with the "finished" label and computes verify_data as HMAC(finished_key, transcript_hash). The output length is the selected hash digest size.

Parameters

hash	[qsc_tls_hash_algorithm] Hash algorithm selector.
basekey	[const uint8_t*] Pointer to the base traffic secret used to derive finished_key.
basekeylen	[size_t] Length, in bytes, of the base key.
transcripthash	[const uint8_t*] Pointer to the transcript hash.
transcripthashlen	[size_t] Length, in bytes, of the transcript hash.
output	[uint8_t*] Pointer to the verify_data output buffer.
outlen	[size_t] Length, in bytes, of the output buffer.
written	[size_t*] Pointer receiving the number of bytes written.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_compute_psk_binder()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_compute_psk_binder	(	qsc_tls_hash_algorithm	hash,
		const uint8_t *	binderkey,
		size_t	binderkeylen,
		const uint8_t *	partialtranshash,
		size_t	transcripthashlen,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written )

Compute a TLS 1.3 PSK binder MAC.

Computes the PSK binder as HMAC(finished_key, transcript_hash_up_to_binders), where finished_key is derived from the binder key by HKDF-Expand-Label using the "finished" label. The transcript hash must cover the ClientHello through the PSK identities vector and must exclude the binder values themselves.

Parameters

hash	[qsc_tls_hash_algorithm] Hash algorithm selector.
binderkey	[const uint8_t*] Pointer to the derived binder key.
binderkeylen	[size_t] Length, in bytes, of the binder key.
partialtranshash	[const uint8_t*] Pointer to the ClientHello transcript hash up to the binders.
transcripthashlen	[size_t] Length, in bytes, of the transcript hash.
output	[uint8_t*] Pointer to the binder output buffer.
outlen	[size_t] Length, in bytes, of the output buffer.
written	[size_t*] Pointer receiving the number of binder bytes written.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_derive_application_traffic_secrets()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_derive_application_traffic_secrets	(	qsc_tls_key_schedule_state *	state,
		const uint8_t *	transcripthash,
		size_t	transcripthashlen )

Derive the client and server application traffic secrets.

Derives c ap traffic 0 and s ap traffic 0 from master_secret using the transcript hash that includes the server Finished message. These secrets are used to derive application-data record protection keys.

Parameters

state	[qsc_tls_key_schedule_state*] Pointer to an initialized key schedule state with master_secret derived.
transcripthash	[const uint8_t*] Pointer to the application traffic transcript hash.
transcripthashlen	[size_t] Length, in bytes, of the transcript hash.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_derive_binder_key()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_derive_binder_key	(	qsc_tls_key_schedule_state *	state,
		bool	external )

Derive the TLS 1.3 PSK binder key.

Derives the binder key from early_secret for PSK binder computation. The external flag selects the TLS 1.3 "ext binder" label for externally provisioned PSKs or the "res binder" label for resumption PSKs. The early secret must already have been extracted.

Parameters

state	[qsc_tls_key_schedule_state*] Pointer to an initialized key schedule state with early_secret derived.
external	[bool] Set to true for external PSKs; set to false for resumption PSKs.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success, or an error status on invalid state or derivation failure.

◆ qsc_tls_keyschedule_derive_client_early_traffic_secret()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_derive_client_early_traffic_secret	(	qsc_tls_key_schedule_state *	state,
		const uint8_t *	transcripthash,
		size_t	transcripthashlen )

Derive the client early traffic secret for 0-RTT data.

Derives client_early_traffic_secret from early_secret using the ClientHello transcript hash up to, but not including, the PSK binder values. The early secret must already have been extracted.

Parameters

state	[qsc_tls_key_schedule_state*] Pointer to an initialized key schedule state with early_secret derived.
transcripthash	[const uint8_t*] Pointer to the partial ClientHello transcript hash.
transcripthashlen	[size_t] Length, in bytes, of the transcript hash.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_derive_early_exporter_secret()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_derive_early_exporter_secret	(	qsc_tls_key_schedule_state *	state,
		const uint8_t *	transcripthash,
		size_t	transcripthashlen )

Derive the early exporter master secret.

Derives early_exporter_master_secret from early_secret using the supplied ClientHello transcript hash. This secret is used by exporter interfaces that are valid during early-data processing.

Parameters

state	[qsc_tls_key_schedule_state*] Pointer to an initialized key schedule state with early_secret derived.
transcripthash	[const uint8_t*] Pointer to the relevant ClientHello transcript hash.
transcripthashlen	[size_t] Length, in bytes, of the transcript hash.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_derive_exporter_master_secret()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_derive_exporter_master_secret	(	qsc_tls_key_schedule_state *	state,
		const uint8_t *	transcripthash,
		size_t	transcripthashlen )

Derive the exporter master secret.

Derives the exporter master secret from master_secret and the supplied transcript hash. The resulting secret may be used by exporter interfaces that bind external application keys to the TLS session.

Parameters

state	[qsc_tls_key_schedule_state*] Pointer to an initialized key schedule state with master_secret derived.
transcripthash	[const uint8_t*] Pointer to the exporter transcript hash.
transcripthashlen	[size_t] Length, in bytes, of the transcript hash.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_derive_handshake_traffic_secrets()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_derive_handshake_traffic_secrets	(	qsc_tls_key_schedule_state *	state,
		const uint8_t *	transcripthash,
		size_t	transcripthashlen )

Derive the client and server handshake traffic secrets.

Derives c hs traffic and s hs traffic from handshake_secret using the ClientHello through ServerHello transcript hash. These secrets are used to derive the handshake record protection keys.

Parameters

state	[qsc_tls_key_schedule_state*] Pointer to an initialized key schedule state with handshake_secret derived.
transcripthash	[const uint8_t*] Pointer to the ClientHello through ServerHello transcript hash.
transcripthashlen	[size_t] Length, in bytes, of the transcript hash.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_derive_resumption_master_secret()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_derive_resumption_master_secret	(	qsc_tls_key_schedule_state *	state,
		const uint8_t *	transcripthash,
		size_t	transcripthashlen )

Derive the resumption master secret.

Derives the resumption master secret from master_secret and the supplied transcript hash. The resulting secret is used with per-ticket nonces to derive session resumption PSKs.

Parameters

state	[qsc_tls_key_schedule_state*] Pointer to an initialized key schedule state with master_secret derived.
transcripthash	[const uint8_t*] Pointer to the resumption transcript hash.
transcripthashlen	[size_t] Length, in bytes, of the transcript hash.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_derive_resumption_psk()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_derive_resumption_psk	(	const qsc_tls_key_schedule_state *	state,
		const uint8_t *	nonce,
		size_t	noncelen,
		uint8_t *	output,
		size_t	outlen )

Derive a resumption PSK from the resumption master secret.

Computes PSK = HKDF-Expand-Label(resumption_master_secret, "resumption", ticket_nonce, Hash.length). The caller must derive the resumption master secret before invoking this function.

Parameters

state	[const qsc_tls_key_schedule_state*] Pointer to an initialized key schedule state with resumption_master_secret derived.
nonce	[const uint8_t*] Pointer to the per-ticket nonce from the NewSessionTicket message.
noncelen	[size_t] Length, in bytes, of the ticket nonce.
output	[uint8_t*] Pointer to the destination PSK buffer.
outlen	[size_t] Number of PSK bytes to derive, typically Hash.length.

Returns: [qsc_tls_status] Returns qsc_tls_status_success.

◆ qsc_tls_keyschedule_derive_secret_empty()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_derive_secret_empty	(	qsc_tls_hash_algorithm	hash,
		const uint8_t *	secret,
		size_t	secretlen,
		const char *	label,
		size_t	labellen,
		uint8_t *	output,
		size_t	outlen )

Derive a TLS 1.3 secret using the hash of the empty string.

Computes Derive-Secret(secret, label, "") by using the digest of the empty transcript as the HKDF-Expand-Label context. This operation is used for the TLS 1.3 derived-secret boundary between extraction stages.

Parameters

hash	[qsc_tls_hash_algorithm] Hash algorithm selector.
secret	[const uint8_t*] Pointer to the base secret.
secretlen	[size_t] Length, in bytes, of the base secret.
label	[const char*] Pointer to the derivation label.
labellen	[size_t] Length, in bytes, of `label`.
output	[uint8_t*] Pointer to the destination secret buffer.
outlen	[size_t] Length, in bytes, of the destination buffer.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_derive_secret_with_hash()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_derive_secret_with_hash	(	qsc_tls_hash_algorithm	hash,
		const uint8_t *	secret,
		size_t	secretlen,
		const char *	label,
		size_t	labellen,
		const uint8_t *	transcripthash,
		size_t	transcripthashlen,
		uint8_t *	output,
		size_t	outlen )

Derive a TLS 1.3 secret using a supplied transcript hash.

Implements Derive-Secret(secret, label, transcript_hash) by invoking HKDF-Expand-Label, with the supplied transcript hash as the context and an output length equal to the selected hash digest size unless otherwise constrained by outlen.

Parameters

hash	[qsc_tls_hash_algorithm] Hash algorithm selector.
secret	[const uint8_t*] Pointer to the base secret.
secretlen	[size_t] Length, in bytes, of the base secret.
label	[const char*] Pointer to the derivation label.
labellen	[size_t] Length, in bytes, of `label`.
transcripthash	[const uint8_t*] Pointer to the transcript hash.
transcripthashlen	[size_t] Length, in bytes, of the transcript hash.
output	[uint8_t*] Pointer to the destination secret buffer.
outlen	[size_t] Length, in bytes, of the destination buffer.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_derive_traffic_keys()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_derive_traffic_keys	(	qsc_tls_hash_algorithm	hash,
		const uint8_t *	trafficsecret,
		size_t	trafficsecretlen,
		size_t	keylen,
		size_t	ivlen,
		uint8_t *	keyoutput,
		uint8_t *	ivoutput )

Derive record protection key and IV material from a traffic secret.

Expands a traffic secret into the AEAD record protection key and base IV using the TLS 1.3 "key" and "iv" labels. The caller supplies the key and IV lengths associated with the negotiated cipher suite.

Parameters

hash	[qsc_tls_hash_algorithm] Hash algorithm selector.
trafficsecret	[const uint8_t*] Pointer to the traffic secret.
trafficsecretlen	[size_t] Length, in bytes, of the traffic secret.
keylen	[size_t] Required record protection key length, in bytes.
ivlen	[size_t] Required record protection IV length, in bytes.
keyoutput	[uint8_t*] Pointer to the destination key buffer.
ivoutput	[uint8_t*] Pointer to the destination IV buffer.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_extract_early_secret()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_extract_early_secret	(	qsc_tls_key_schedule_state *	state,
		const uint8_t *	psk,
		size_t	psklen )

Extract the TLS 1.3 early secret.

Computes early_secret = HKDF-Extract(0, PSK). When no PSK is used, the caller supplies NULL with a zero length and the implementation performs the no-PSK TLS 1.3 flow.

Parameters

state	[qsc_tls_key_schedule_state*] Pointer to an initialized key schedule state.
psk	[const uint8_t*] Pointer to the optional PSK, or NULL when `psklen` is zero.
psklen	[size_t] Length, in bytes, of the PSK.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_extract_handshake_secret()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_extract_handshake_secret	(	qsc_tls_key_schedule_state *	state,
		const uint8_t *	dhe,
		size_t	dhelen )

Extract the TLS 1.3 handshake secret.

Computes the handshake secret from the derived early-secret boundary value and the supplied DHE or hybrid shared secret. The early secret must already have been extracted.

Parameters

state	[qsc_tls_key_schedule_state*] Pointer to an initialized key schedule state with early_secret derived.
dhe	[const uint8_t*] Pointer to the DHE, KEM, or hybrid shared secret.
dhelen	[size_t] Length, in bytes, of the shared secret.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_extract_master_secret()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_extract_master_secret ( qsc_tls_key_schedule_state * state )

Extract the TLS 1.3 master secret.

Computes the master secret from the derived handshake-secret boundary value and an all-zero input keying material value. The handshake secret must already have been extracted.

Parameters

state [qsc_tls_key_schedule_state*] Pointer to an initialized key schedule state with handshake_secret derived.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_hkdf_expand()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_hkdf_expand	(	qsc_tls_hash_algorithm	hash,
		const uint8_t *	prk,
		size_t	prklen,
		const uint8_t *	info,
		size_t	infolen,
		uint8_t *	output,
		size_t	outlen )

Perform HKDF-Expand for the selected TLS hash algorithm.

Expands a pseudorandom key into output keying material using the supplied HKDF info value. This is the generic HKDF-Expand primitive used internally by the TLS 1.3 label expansion functions.

Parameters

hash	[qsc_tls_hash_algorithm] Hash algorithm selector.
prk	[const uint8_t*] Pointer to the pseudorandom key.
prklen	[size_t] Length, in bytes, of the pseudorandom key.
info	[const uint8_t*] Pointer to the HKDF info field, or NULL when `infolen` is zero.
infolen	[size_t] Length, in bytes, of the HKDF info field.
output	[uint8_t*] Pointer to the destination output keying material.
outlen	[size_t] Number of bytes to derive.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_hkdf_expand_label()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_hkdf_expand_label	(	qsc_tls_hash_algorithm	hash,
		const uint8_t *	secret,
		size_t	secretlen,
		const char *	label,
		size_t	labellen,
		const uint8_t *	context,
		size_t	contextlen,
		uint8_t *	output,
		size_t	outlen )

Perform TLS 1.3 HKDF-Expand-Label.

Encodes the TLS 1.3 HkdfLabel structure as: uint16 length, opaque label vector containing the literal prefix "tls13 " followed by label, and an opaque context vector. The encoded label is then supplied to HKDF-Expand.

Parameters

hash	[qsc_tls_hash_algorithm] Hash algorithm selector.
secret	[const uint8_t*] Pointer to the input secret.
secretlen	[size_t] Length, in bytes, of the input secret.
label	[const char*] Pointer to the TLS label string without the "tls13 " prefix.
labellen	[size_t] Length, in bytes, of `label`.
context	[const uint8_t*] Pointer to the context value, or NULL when `contextlen` is zero.
contextlen	[size_t] Length, in bytes, of the context value.
output	[uint8_t*] Pointer to the destination output buffer.
outlen	[size_t] Number of bytes to derive.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_hkdf_extract()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_hkdf_extract	(	qsc_tls_hash_algorithm	hash,
		const uint8_t *	salt,
		size_t	saltlen,
		const uint8_t *	ikm,
		size_t	ikmlen,
		uint8_t *	output,
		size_t	outlen )

Perform HKDF-Extract for the selected TLS hash algorithm.

Computes an HKDF pseudorandom key from the supplied salt and input keying material. The output length must match the digest size of the selected hash algorithm.

Parameters

hash	[qsc_tls_hash_algorithm] Hash algorithm selector.
salt	[const uint8_t*] Pointer to the salt buffer, or NULL when `saltlen` is zero.
saltlen	[size_t] Length, in bytes, of the salt buffer.
ikm	[const uint8_t*] Pointer to the input keying material.
ikmlen	[size_t] Length, in bytes, of the input keying material.
output	[uint8_t*] Pointer to the destination pseudorandom key buffer.
outlen	[size_t] Length, in bytes, of the destination buffer.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_state_dispose()

QSC_EXPORT_API void qsc_tls_keyschedule_state_dispose ( qsc_tls_key_schedule_state * state )

Dispose of a TLS key schedule state.

Zeroizes all stored secrets, clears state flags, and returns the state object to an inert value. This function should be called for every initialized key schedule state before the associated connection is released.

Parameters

state [qsc_tls_key_schedule_state*] Pointer to the key schedule state to dispose.

◆ qsc_tls_keyschedule_state_initialize()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_state_initialize	(	qsc_tls_key_schedule_state *	state,
		qsc_tls_hash_algorithm	hash )

Initialize a TLS key schedule state.

Clears the supplied state object, records the negotiated hash algorithm, and resolves the digest size used by all subsequent key schedule operations.

Parameters

state	[qsc_tls_key_schedule_state*] Pointer to the key schedule state to initialize.
hash	[qsc_tls_hash_algorithm] Negotiated TLS hash algorithm.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_suite_hash()

QSC_EXPORT_API qsc_tls_hash_algorithm qsc_tls_keyschedule_suite_hash ( qsc_tls_cipher_suite suite )

Resolve the hash algorithm associated with a TLS cipher suite.

Returns the transcript and HKDF hash algorithm used by the specified cipher suite. Unsupported suites return the implementation-defined invalid or none hash selector.

Parameters

suite [qsc_tls_cipher_suite] TLS cipher suite selector.

Returns: [qsc_tls_hash_algorithm] Returns the hash algorithm associated with the cipher suite.

◆ qsc_tls_keyschedule_suite_record_sizes()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_suite_record_sizes	(	qsc_tls_cipher_suite	suite,
		size_t *	keylen,
		size_t *	ivlen )

Resolve record protection key and IV lengths for a TLS cipher suite.

Maps the negotiated cipher suite to the AEAD key length and base IV length required by TLS record protection.

Parameters

suite	[qsc_tls_cipher_suite] TLS cipher suite selector.
keylen	[size_t*] Pointer receiving the record protection key length.
ivlen	[size_t*] Pointer receiving the record protection IV length.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_keyschedule_verify_finished()

QSC_EXPORT_API qsc_tls_status qsc_tls_keyschedule_verify_finished	(	qsc_tls_hash_algorithm	hash,
		const uint8_t *	basekey,
		size_t	basekeylen,
		const uint8_t *	transcripthash,
		size_t	transcripthashlen,
		const uint8_t *	candidate,
		size_t	candidatelen )

Verify a TLS 1.3 Finished verify_data value.

Recomputes the expected Finished MAC and compares it to the supplied candidate using constant-time comparison. The candidate length must match the selected hash digest size.

Parameters

hash	[qsc_tls_hash_algorithm] Hash algorithm selector.
basekey	[const uint8_t*] Pointer to the base traffic secret used to derive finished_key.
basekeylen	[size_t] Length, in bytes, of the base key.
transcripthash	[const uint8_t*] Pointer to the transcript hash.
transcripthashlen	[size_t] Length, in bytes, of the transcript hash.
candidate	[const uint8_t*] Pointer to the received verify_data value.
candidatelen	[size_t] Length, in bytes, of the candidate value.

Returns: [qsc_tls_status] Returns qsc_tls_status_success.

Data Structures

Typedefs

Functions

Detailed Description

Usage

Function Documentation

◆ qsc_tls_keyschedule_advance_traffic_secret()

◆ qsc_tls_keyschedule_build_certificate_verify_input()

◆ qsc_tls_keyschedule_compute_finished()

◆ qsc_tls_keyschedule_compute_psk_binder()

◆ qsc_tls_keyschedule_derive_application_traffic_secrets()

◆ qsc_tls_keyschedule_derive_binder_key()

◆ qsc_tls_keyschedule_derive_client_early_traffic_secret()

◆ qsc_tls_keyschedule_derive_early_exporter_secret()

◆ qsc_tls_keyschedule_derive_exporter_master_secret()

◆ qsc_tls_keyschedule_derive_handshake_traffic_secrets()

◆ qsc_tls_keyschedule_derive_resumption_master_secret()

◆ qsc_tls_keyschedule_derive_resumption_psk()

◆ qsc_tls_keyschedule_derive_secret_empty()

◆ qsc_tls_keyschedule_derive_secret_with_hash()

◆ qsc_tls_keyschedule_derive_traffic_keys()

◆ qsc_tls_keyschedule_extract_early_secret()

◆ qsc_tls_keyschedule_extract_handshake_secret()

◆ qsc_tls_keyschedule_extract_master_secret()

◆ qsc_tls_keyschedule_hkdf_expand()

◆ qsc_tls_keyschedule_hkdf_expand_label()

◆ qsc_tls_keyschedule_hkdf_extract()

◆ qsc_tls_keyschedule_state_dispose()

◆ qsc_tls_keyschedule_state_initialize()

◆ qsc_tls_keyschedule_suite_hash()

◆ qsc_tls_keyschedule_suite_record_sizes()

◆ qsc_tls_keyschedule_verify_finished()