TLS 1.3 server handshake state machine. More...

#include "qsccommon.h"
#include "tlserrors.h"
#include "tlstypes.h"
#include "tlsstate.h"
#include "tlslimits.h"
#include "tlscert.h"
#include "tlsgroups.h"
#include "tlskeyschedule.h"
#include "tlstranscript.h"

Data Structures
struct	qsc_tls_server_certificate_identity
	A server certificate identity selectable by SNI. More...
struct	qsc_tls_server_config
	Immutable server configuration. More...
struct	qsc_tls_server_state
	Server handshake state container. More...

Typedefs
typedef enum qsc_tls_server_state_phase	qsc_tls_server_state_phase
typedef bool(*	qsc_tls_psk_lookup_callback) (const uint8_t identity, size_t identitylen, uint8_t psk_out, size_t pskcap, size_t psk_len_out, qsc_tls_cipher_suite suite_out, uint32_t max_early_data_out, void state)
	Server-side PSK lookup callback.
typedef struct qsc_tls_server_certificate_identity	qsc_tls_server_certificate_identity
typedef struct qsc_tls_server_config	qsc_tls_server_config
typedef struct qsc_tls_server_state	qsc_tls_server_state

Enumerations

enum qsc_tls_server_state_phase {
qsc_tls_server_phase_initial = 0 , qsc_tls_server_phase_waiting_client_hello = 1 , qsc_tls_server_phase_waiting_client_hello_2 = 2 , qsc_tls_server_phase_sending_flight1 = 3 ,
qsc_tls_server_phase_waiting_client_certificate = 4 , qsc_tls_server_phase_waiting_client_certificate_verify = 5 , qsc_tls_server_phase_waiting_client_finished = 6 , qsc_tls_server_phase_established = 7 ,
qsc_tls_server_phase_closed = 8 , qsc_tls_server_phase_failed = 9 , qsc_tls_server_phase_waiting_end_of_early_data = 10
}

Functions
QSC_EXPORT_API qsc_tls_status	qsc_tls_server_config_set_certificate_interface (qsc_tls_server_config config, const qsc_tls_certificate_interface iface, bool requestclientauth, bool requireclientauth)
	Copy a client-certificate validation interface into a TLS server configuration.
QSC_EXPORT_API qsc_tls_status	qsc_tls_server_config_set_client_authorization (qsc_tls_server_config config, qsc_tls_client_authorization_callback callback, void state, bool required)
	Configure the server-side mTLS application authorization callback.
QSC_EXPORT_API qsc_tls_status	qsc_tls_server_authorize_client_certificate (qsc_tls_server_state state, const qsc_tls_certificate_view chain, size_t chainlength)
	Validate and authorize a presented mTLS client certificate chain.
QSC_EXPORT_API qsc_tls_status	qsc_tls_server_config_set_local_certificate (qsc_tls_server_config config, const qsc_tls_certificate_view chain, size_t chainlength, qsc_tls_signature_scheme verifyscheme, const uint8_t *privatekeydata, size_t privatekeylen)
	Copy a local certificate chain and private signing key into a TLS server configuration.
QSC_EXPORT_API qsc_tls_status	qsc_tls_server_config_add_certificate_identity (qsc_tls_server_config config, const char hostname, const qsc_tls_local_certificate_config *localcert)
	Add an SNI-selectable certificate identity to a TLS server configuration.
QSC_EXPORT_API qsc_tls_status	qsc_tls_server_config_set_sni_required (qsc_tls_server_config *config, bool required)
	Configure whether the server requires a recognized SNI hostname.
QSC_EXPORT_API qsc_tls_status	qsc_tls_server_initialize (qsc_tls_server_state state, const qsc_tls_server_config config)
QSC_EXPORT_API void	qsc_tls_server_dispose (qsc_tls_server_state *state)
QSC_EXPORT_API qsc_tls_status	qsc_tls_server_process_record (qsc_tls_server_state state, const uint8_t input, size_t inlen, size_t consumed, uint8_t output, size_t outlen, size_t *written)
	Process an inbound record and optionally produce an outbound flight.
QSC_EXPORT_API bool	qsc_tls_server_is_handshake_complete (const qsc_tls_server_state *state)
QSC_EXPORT_API qsc_tls_cipher_suite	qsc_tls_server_get_negotiated_cipher_suite (const qsc_tls_server_state *state)

Detailed Description

TLS 1.3 server handshake state machine.

Typedef Documentation

◆ qsc_tls_psk_lookup_callback

typedef bool(* qsc_tls_psk_lookup_callback) (const uint8_t *identity, size_t identitylen, uint8_t *psk_out, size_t pskcap, size_t *psk_len_out, qsc_tls_cipher_suite *suite_out, uint32_t *max_early_data_out, void *state)

Server-side PSK lookup callback.

Invoked for each PskIdentity offered by a client. Must fill psk_out with the expected resumption PSK bytes (previously derived server-side at NST emission time and keyed on the ticket opaque bytes) if recognized.

Returns: true when the PSK for this identity was found and returned.

Enumeration Type Documentation

◆ qsc_tls_server_state_phase

enum qsc_tls_server_state_phase

Enumerator
qsc_tls_server_phase_initial	Not yet started.
qsc_tls_server_phase_waiting_client_hello	Waiting first ClientHello.
qsc_tls_server_phase_waiting_client_hello_2	After HRR.
qsc_tls_server_phase_sending_flight1	Producing SH..Finished.
qsc_tls_server_phase_waiting_client_certificate	mTLS Certificate expected.
qsc_tls_server_phase_waiting_end_of_early_data	0-RTT accepted; waiting EndOfEarlyData before client Finished.

Function Documentation

◆ qsc_tls_server_authorize_client_certificate()

QSC_EXPORT_API qsc_tls_status qsc_tls_server_authorize_client_certificate	(	qsc_tls_server_state *	state,
		const qsc_tls_certificate_view *	chain,
		size_t	chainlength )

Validate and authorize a presented mTLS client certificate chain.

This helper performs the server-side mTLS chain validation step, prepares a bounded authorization information structure, and then evaluates the configured application authorization callback. CertificateVerify possession checking is performed separately by the TLS handshake state machine.

Parameters

state	[struct*] The server handshake state.
chain	[const struct*] Client certificate chain views in leaf-first order.
chainlength	[size_t] Number of certificate views in the chain.

Returns: [qsc_tls_status] Returns qsc_tls_status_success when the certificate is valid and authorized.

◆ qsc_tls_server_config_add_certificate_identity()

QSC_EXPORT_API qsc_tls_status qsc_tls_server_config_add_certificate_identity	(	qsc_tls_server_config *	config,
		const char *	hostname,
		const qsc_tls_local_certificate_config *	localcert )

Add an SNI-selectable certificate identity to a TLS server configuration.

Parameters

config	[struct*] The server configuration to update.
hostname	[const char*] The DNS name or wildcard pattern for this identity.
localcert	[const struct*] The local certificate configuration for the identity.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_server_config_set_certificate_interface()

QSC_EXPORT_API qsc_tls_status qsc_tls_server_config_set_certificate_interface	(	qsc_tls_server_config *	config,
		const qsc_tls_certificate_interface *	iface,
		bool	requestclientauth,
		bool	requireclientauth )

Copy a client-certificate validation interface into a TLS server configuration.

This setter is the TLS-side attachment point for mutual-TLS peer validation. X.509 helpers prepare the qsc_tls_certificate_interface, but do not mutate TLS server state directly.

Parameters

config	[struct*] The server configuration to update.
iface	[struct*] Optional certificate-validation interface. Required when client authentication is requested or required.
requestclientauth	[bool] Send CertificateRequest when true.
requireclientauth	[bool] Reject an empty client Certificate when true.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_server_config_set_client_authorization()

QSC_EXPORT_API qsc_tls_status qsc_tls_server_config_set_client_authorization	(	qsc_tls_server_config *	config,
		qsc_tls_client_authorization_callback	callback,
		void *	state,
		bool	required )

Configure the server-side mTLS application authorization callback.

The callback is evaluated only after certificate-chain validation has accepted the client certificate. If required is true, a missing callback or a callback rejection denies the peer. If required is false, a missing callback leaves cryptographic certificate validation as the authorization boundary.

Parameters

config	[struct*] The server configuration to update.
callback	[function] Optional application authorization callback.
state	[void*] Caller-owned state passed to the callback.
required	[bool] Require callback acceptance when true.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_server_config_set_local_certificate()

QSC_EXPORT_API qsc_tls_status qsc_tls_server_config_set_local_certificate	(	qsc_tls_server_config *	config,
		const qsc_tls_certificate_view *	chain,
		size_t	chainlength,
		qsc_tls_signature_scheme	verifyscheme,
		const uint8_t *	privatekeydata,
		size_t	privatekeylen )

Copy a local certificate chain and private signing key into a TLS server configuration.

The certificate views are copied as non-owning DER pointers. The pointed-to DER buffers must remain valid for the lifetime of handshakes initialized from this configuration. The private key bytes are copied into the configuration and are used by the TLS CertificateVerify signing callback at handshake time.

Parameters

config	[struct*] The server configuration to update.
chain	[struct*] Certificate chain views in leaf-first order.
chainlength	[size_t] Number of valid chain entries.
verifyscheme	[enum] TLS CertificateVerify signature scheme.
privatekeydata	[const uint8_t*] Raw private key bytes for the signing scheme.
privatekeylen	[size_t] Length of the private key.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_server_config_set_sni_required()

QSC_EXPORT_API qsc_tls_status qsc_tls_server_config_set_sni_required	(	qsc_tls_server_config *	config,
		bool	required )

Configure whether the server requires a recognized SNI hostname.

Parameters

config	[struct*] The server configuration to update.
required	[bool] Set to true to reject absent or unmatched SNI names.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ qsc_tls_psk_lookup_callback

Enumeration Type Documentation

◆ qsc_tls_server_state_phase

Function Documentation

◆ qsc_tls_server_authorize_client_certificate()

◆ qsc_tls_server_config_add_certificate_identity()

◆ qsc_tls_server_config_set_certificate_interface()

◆ qsc_tls_server_config_set_client_authorization()

◆ qsc_tls_server_config_set_local_certificate()

◆ qsc_tls_server_config_set_sni_required()