tlsclient.h File Reference

TLS 1.3 client handshake state machine declarations. More...

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

Go to the source code of this file.

Data Structures
struct	qsc_tls_client_config
	Stores the static client policy used to initialize a TLS client state. More...
struct	qsc_tls_client_state
	Stores the active TLS 1.3 client handshake and record state. More...

Typedefs
typedef enum qsc_tls_client_phase	qsc_tls_client_phase
typedef struct qsc_tls_client_config	qsc_tls_client_config
typedef struct qsc_tls_client_state	qsc_tls_client_state

Enumerations
enum	qsc_tls_client_phase {   qsc_tls_client_phase_initial = 0 , qsc_tls_client_phase_waiting_server_hello = 1 , qsc_tls_client_phase_waiting_encrypted_extensions = 2 , qsc_tls_client_phase_waiting_certificate = 3 ,   qsc_tls_client_phase_waiting_certificate_verify = 4 , qsc_tls_client_phase_waiting_finished = 5 , qsc_tls_client_phase_established = 6 , qsc_tls_client_phase_closed = 7 ,   qsc_tls_client_phase_failed = 8 }
	Enumerates the major phases of the TLS 1.3 client handshake. More...

Functions
QSC_EXPORT_API qsc_tls_status	qsc_tls_client_config_set_certificate_interface (qsc_tls_client_config *config, const qsc_tls_certificate_interface *iface, const char *hostname)
	Initialize a TLS client handshake state.
QSC_EXPORT_API qsc_tls_status	qsc_tls_client_initialize (qsc_tls_client_state *state, const qsc_tls_client_config *config)
QSC_EXPORT_API void	qsc_tls_client_dispose (qsc_tls_client_state *state)
	Dispose of a TLS client handshake state.
QSC_EXPORT_API qsc_tls_status	qsc_tls_client_send_hello (qsc_tls_client_state *state, uint8_t *output, size_t outlen, size_t *written)
	Build the initial ClientHello flight.
QSC_EXPORT_API qsc_tls_status	qsc_tls_client_process_record (qsc_tls_client_state *state, const uint8_t *input, size_t inlen, size_t *consumed, uint8_t *output, size_t outlen, size_t *written)
	Process an inbound TLS record and optionally emit a response flight.
QSC_EXPORT_API bool	qsc_tls_client_is_handshake_complete (const qsc_tls_client_state *state)
	Determine whether the client handshake is complete.
QSC_EXPORT_API qsc_tls_cipher_suite	qsc_tls_client_get_negotiated_cipher_suite (const qsc_tls_client_state *state)
	Get the cipher suite negotiated by the server.

Detailed Description

TLS 1.3 client handshake state machine declarations.

tlsclient.c - TLS 1.3 client handshake state machine.

This MVP covers the 1-RTT non-PSK, non-HRR path: send_hello -> phase_waiting_server_hello process ServerHello -> install handshake keys, phase_waiting_encrypted_extensions process EncryptedExt -> phase_waiting_certificate process Certificate -> phase_waiting_certificate_verify process CertVerify -> phase_waiting_finished process Finished -> derive app keys, emit client Finished, phase_established

HRR and PSK paths are not implemented in this MVP. Unsupported flows return qsc_tls_status_not_supported with the state set to failed.

This header declares the client-side handshake driver used by the TLS engine. The current implementation is centered on the TLS 1.3 1-RTT certificate-authenticated path. It tracks transcript state, negotiated algorithms, key schedule progression, and the read/write record states required to transition from the handshake epoch to application traffic.

The client state does not own application transport resources. Callers supply encoded record buffers to the process function and receive any outbound record material through the provided output buffer.

Enumeration Type Documentation

qsc_tls_client_phase

enum qsc_tls_client_phase

Enumerates the major phases of the TLS 1.3 client handshake.

Enumerator
qsc_tls_client_phase_initial	State has been initialized and no ClientHello has been emitted.
qsc_tls_client_phase_waiting_server_hello	ClientHello has been sent and the client is awaiting ServerHello.
qsc_tls_client_phase_waiting_encrypted_extensions	Handshake keys are installed and the client is awaiting EncryptedExtensions.
qsc_tls_client_phase_waiting_certificate	The client is awaiting the server Certificate message.
qsc_tls_client_phase_waiting_certificate_verify	The client is awaiting the server CertificateVerify message.
qsc_tls_client_phase_waiting_finished	The client is awaiting the server Finished message.
qsc_tls_client_phase_established	The handshake completed successfully and application traffic keys are active.
qsc_tls_client_phase_closed	The connection has been closed locally or by peer notification.
qsc_tls_client_phase_failed	A fatal error occurred and the handshake or connection failed.

Function Documentation

qsc_tls_client_config_set_certificate_interface()

QSC_EXPORT_API qsc_tls_status qsc_tls_client_config_set_certificate_interface	(	qsc_tls_client_config *	config,
		const qsc_tls_certificate_interface *	iface,
		const char *	hostname )

Initialize a TLS client handshake state.

Clears the supplied state object, copies the client policy, selects the initial handshake phase, and prepares the client for ClientHello emission. The configuration arrays referenced by config must remain valid for the lifetime of the client state.

Parameters

state	[struct*] The client state to initialize.
config	[const struct*] The client configuration and algorithm policy.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.

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

This setter is the TLS-side attachment point for certificate validation. X.509 helpers prepare the qsc_tls_certificate_interface, but do not mutate TLS state objects directly. The hostname pointer is borrowed from the caller and must remain valid for the lifetime of configurations initialized from this object.

Parameters

config	[struct*] The client configuration to update.
iface	[struct*] The certificate-validation interface to copy.
hostname	[const char*] Optional server hostname for SNI and certificate validation.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.

qsc_tls_client_dispose()

QSC_EXPORT_API void qsc_tls_client_dispose

(

qsc_tls_client_state *

state

)

Dispose of a TLS client handshake state.

Clears record keys, transcript state, and any retained handshake material. The structure is left in a fully erased state.

Parameters

state

[struct*] The client state to clear.

qsc_tls_client_get_negotiated_cipher_suite()

QSC_EXPORT_API qsc_tls_cipher_suite qsc_tls_client_get_negotiated_cipher_suite

(

const qsc_tls_client_state *

state

)

Get the cipher suite negotiated by the server.

Parameters

state

[const struct*] The client state to query.

Returns

[qsc_tls_cipher_suite] Returns the negotiated cipher suite, or an unspecified value if negotiation has not completed.

qsc_tls_client_is_handshake_complete()

QSC_EXPORT_API bool qsc_tls_client_is_handshake_complete

(

const qsc_tls_client_state *

state

)

Determine whether the client handshake is complete.

Parameters

state

[const struct*] The client state to query.

Returns

[bool] Returns true if the client reached the established phase.

qsc_tls_client_process_record()

QSC_EXPORT_API qsc_tls_status qsc_tls_client_process_record	(	qsc_tls_client_state *	state,
		const uint8_t *	input,
		size_t	inlen,
		size_t *	consumed,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written )

Process an inbound TLS record and optionally emit a response flight.

Consumes one or more bytes of inbound TLS record material, advances the client handshake state machine, and emits any required response records into output. The function is used by the engine to process ServerHello, encrypted handshake messages, alerts, and post-transition client Finished output.

Parameters

state	[struct*] The active client handshake state.
input	[const uint8_t*] The inbound record bytes.
inlen	[size_t] The number of inbound bytes available in input.
consumed	[size_t*] Receives the number of inbound bytes consumed.
output	[uint8_t*] The destination buffer for any outbound response records.
outlen	[size_t] The destination buffer length in bytes.
written	[size_t*] Receives the number of bytes written to output.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.

qsc_tls_client_send_hello()

QSC_EXPORT_API qsc_tls_status qsc_tls_client_send_hello	(	qsc_tls_client_state *	state,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written )

Build the initial ClientHello flight.

Encodes a ClientHello record according to the configured cipher suites, groups, signature schemes, and hostname. On success the client advances into the phase that awaits ServerHello.

Parameters

state	[struct*] The active client handshake state.
output	[uint8_t*] The destination output buffer.
outlen	[size_t] The destination buffer length in bytes.
written	[size_t*] Receives the number of bytes written to output.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.