tlsengine.h File Reference

TLS 1.3 record engine, connection wrapper, handshake driver, application data transport, key update, and session ticket interface. More...

#include "qsccommon.h"
#include "tlserrors.h"
#include "tlstypes.h"
#include "tlslimits.h"
#include "tlsstate.h"
#include "tlsclient.h"
#include "tlsserver.h"
#include "tlssession.h"

Go to the source code of this file.

Data Structures
struct	qsc_tls_connection
	Unified TLS engine connection context. More...

Typedefs
typedef enum qsc_tls_role	qsc_tls_role
typedef struct qsc_tls_connection	qsc_tls_connection

Enumerations
enum	qsc_tls_role { qsc_tls_role_client = 0 , qsc_tls_role_server = 1 }
	TLS engine endpoint role. More...

Functions
QSC_EXPORT_API qsc_tls_status	qsc_tls_engine_initialize_client (qsc_tls_connection *connection, const qsc_tls_client_config *config)
	Initialize a TLS engine connection as a client.
QSC_EXPORT_API qsc_tls_status	qsc_tls_engine_initialize_server (qsc_tls_connection *connection, const qsc_tls_server_config *config)
	Initialize a TLS engine connection as a server.
QSC_EXPORT_API void	qsc_tls_engine_dispose (qsc_tls_connection *connection)
	Dispose of a TLS engine connection.
QSC_EXPORT_API qsc_tls_status	qsc_tls_engine_handshake (qsc_tls_connection *connection, const uint8_t *input, size_t inlen, size_t *consumed, uint8_t *output, size_t outlen, size_t *written)
	Advance the TLS handshake state machine.
QSC_EXPORT_API qsc_tls_status	qsc_tls_engine_write_application_data (qsc_tls_connection *connection, const uint8_t *input, size_t inlen, uint8_t *output, size_t outlen, size_t *written)
	Encrypt and frame application data.
QSC_EXPORT_API qsc_tls_status	qsc_tls_engine_read_application_data (qsc_tls_connection *connection, const uint8_t *input, size_t inlen, size_t *consumed, uint8_t *output, size_t outlen, size_t *written)
	Decrypt inbound application records.
QSC_EXPORT_API qsc_tls_status	qsc_tls_engine_read_application_data_ex (qsc_tls_connection *connection, const uint8_t *input, size_t inlen, size_t *consumed, uint8_t *output, size_t outlen, size_t *written, uint8_t *responseoutput, size_t responseoutlen, size_t *responsewritten)
	Decrypt inbound records and process post-handshake messages.
QSC_EXPORT_API qsc_tls_status	qsc_tls_engine_request_key_update (qsc_tls_connection *connection, bool requestpeerupdate, uint8_t *output, size_t outlen, size_t *written)
	Initiate a TLS 1.3 KeyUpdate operation.
QSC_EXPORT_API qsc_tls_status	qsc_tls_engine_emit_session_ticket (qsc_tls_connection *connection, uint32_t lifetime_seconds, uint8_t *output, size_t outlen, size_t *written, qsc_tls_session_ticket *ticketout)
	Emit a TLS 1.3 NewSessionTicket record.
QSC_EXPORT_API qsc_tls_status	qsc_tls_engine_consume_session_ticket (qsc_tls_connection *connection, const uint8_t *input, size_t inlen, size_t *consumed, qsc_tls_session_ticket *ticketout)
	Consume a TLS 1.3 NewSessionTicket record.
QSC_EXPORT_API qsc_tls_status	qsc_tls_engine_close (qsc_tls_connection *connection, uint8_t *output, size_t outlen, size_t *written)
	Build an encrypted close_notify alert record.
QSC_EXPORT_API bool	qsc_tls_engine_is_handshake_complete (const qsc_tls_connection *connection)
	Test whether the TLS handshake is complete.

Detailed Description

TLS 1.3 record engine, connection wrapper, handshake driver, application data transport, key update, and session ticket interface.

This header defines the QSC TLS engine interface. The engine provides a unified client/server connection handle and a bounded record-processing layer for the QSC TLS 1.3 implementation. It drives handshake progression, frames encrypted application records, decrypts inbound records, dispatches post-handshake messages, emits and consumes session tickets, and constructs closure alerts.

The engine does not own sockets or transport resources. Callers provide inbound byte buffers and outbound scratch buffers. The engine consumes available TLS records, updates the associated client or server state, and returns any generated handshake, application, alert, KeyUpdate, or NewSessionTicket records through caller-supplied output buffers.

The connection object contains either a client state or server state, selected by role at initialization. All keying material and transient buffers are zeroized by qsc_tls_engine_dispose().

Enumeration Type Documentation

qsc_tls_role

enum qsc_tls_role

TLS engine endpoint role.

This enumeration identifies whether a qsc_tls_connection instance contains client-side or server-side TLS state. The role determines which state object in the connection union is active and which protocol path is used by the engine functions.

Enumerator
qsc_tls_role_client	The connection is operating as a TLS client.
qsc_tls_role_server	The connection is operating as a TLS server.

Function Documentation

qsc_tls_engine_close()

QSC_EXPORT_API qsc_tls_status qsc_tls_engine_close	(	qsc_tls_connection *	connection,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written )

Build an encrypted close_notify alert record.

Constructs a TLS closure alert for the active connection and writes the encrypted close_notify record to the caller-supplied output buffer. The caller is responsible for transmitting the generated record and then closing or draining the underlying transport according to its own I/O policy.

Parameters

connection	[qsc_tls_connection*] Pointer to an initialized TLS engine connection.
output	[uint8_t*] Pointer to the output buffer receiving the close_notify record.
outlen	[size_t] Size, in bytes, of the output buffer.
written	[size_t*] Pointer receiving the number of bytes written to output.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success, or an error status on invalid state, insufficient output capacity, or encryption failure.

qsc_tls_engine_consume_session_ticket()

QSC_EXPORT_API qsc_tls_status qsc_tls_engine_consume_session_ticket	(	qsc_tls_connection *	connection,
		const uint8_t *	input,
		size_t	inlen,
		size_t *	consumed,
		qsc_tls_session_ticket *	ticketout )

Consume a TLS 1.3 NewSessionTicket record.

Decrypts an inbound post-handshake NewSessionTicket record for a client-role connection, parses the ticket body, derives the resumption PSK from the client's resumption_master_secret and the ticket nonce, and writes the parsed ticket metadata to ticketout. The caller may retain the populated ticket structure for later 0-RTT or 1-RTT resumption.

Parameters

connection	[qsc_tls_connection*] Pointer to a client-role TLS engine connection in the established state.
input	[const uint8_t*] Pointer to the encrypted NewSessionTicket record.
inlen	[size_t] Number of inbound bytes available in input.
consumed	[size_t*] Pointer receiving the number of inbound bytes consumed.
ticketout	[qsc_tls_session_ticket*] Pointer receiving the parsed and derived ticket metadata.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success, or an error status on invalid role, invalid state, malformed input, authentication failure, or ticket derivation failure.

qsc_tls_engine_dispose()

QSC_EXPORT_API void qsc_tls_engine_dispose

(

qsc_tls_connection *

connection

)

Dispose of a TLS engine connection.

Releases the active TLS engine state and zeroizes transient buffers, traffic secrets, key schedules, cipher states, and other sensitive material held by the connection context.

Parameters

connection

[qsc_tls_connection*] Pointer to the TLS engine connection context to dispose.

qsc_tls_engine_emit_session_ticket()

QSC_EXPORT_API qsc_tls_status qsc_tls_engine_emit_session_ticket	(	qsc_tls_connection *	connection,
		uint32_t	lifetime_seconds,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written,
		qsc_tls_session_ticket *	ticketout )

Emit a TLS 1.3 NewSessionTicket record.

Builds a NewSessionTicket handshake message for a server-role connection in the established state. The function generates the ticket nonce and ticket identifier, derives the per-ticket resumption secret from the resumption_master_secret, encrypts the handshake message under the server application write traffic keys, and returns the generated ticket metadata to the caller.

Parameters

connection	[qsc_tls_connection*] Pointer to a server-role TLS engine connection in the established state.
lifetime_seconds	[uint32_t] Ticket lifetime value, in seconds, to advertise to the client.
output	[uint8_t*] Pointer to the output buffer receiving the encrypted NewSessionTicket record.
outlen	[size_t] Size, in bytes, of the output buffer.
written	[size_t*] Pointer receiving the number of bytes written to output.
ticketout	[qsc_tls_session_ticket*] Pointer receiving the generated ticket metadata, including nonce, ticket value, lifetime, age-add value, cipher suite, and derived resumption secret.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success, or an error status on invalid role, invalid state, insufficient output capacity, or cryptographic failure.

qsc_tls_engine_handshake()

QSC_EXPORT_API qsc_tls_status qsc_tls_engine_handshake	(	qsc_tls_connection *	connection,
		const uint8_t *	input,
		size_t	inlen,
		size_t *	consumed,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written )

Advance the TLS handshake state machine.

Processes inbound handshake or record-layer bytes and writes any generated outbound TLS flight to the supplied output buffer. The caller should invoke this function repeatedly as network data becomes available until qsc_tls_engine_is_handshake_complete() returns true.

The function reports how many inbound bytes were consumed and how many outbound bytes were produced. The engine does not perform socket I/O.

Parameters

connection	[qsc_tls_connection*] Pointer to an initialized TLS engine connection.
input	[const uint8_t*] Pointer to inbound TLS bytes. This value may be NULL when inlen is zero.
inlen	[size_t] Number of bytes available in input.
consumed	[size_t*] Pointer receiving the number of inbound bytes consumed by the engine.
output	[uint8_t*] Pointer to the caller-supplied outbound buffer.
outlen	[size_t] Size, in bytes, of the outbound buffer.
written	[size_t*] Pointer receiving the number of outbound bytes written to output.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success, or an error status on malformed input, insufficient output capacity, invalid state, or cryptographic failure.

qsc_tls_engine_initialize_client()

QSC_EXPORT_API qsc_tls_status qsc_tls_engine_initialize_client	(	qsc_tls_connection *	connection,
		const qsc_tls_client_config *	config )

Initialize a TLS engine connection as a client.

Initializes the supplied connection object for client-side TLS operation using the caller-provided client configuration. The function clears and prepares the connection state, selects the client role, and initializes the embedded client protocol context.

Parameters

connection	[qsc_tls_connection*] Pointer to the TLS engine connection context to initialize.
config	[const qsc_tls_client_config*] Pointer to the client configuration used to initialize the client protocol state.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success, or an error status on invalid input or initialization failure.

qsc_tls_engine_initialize_server()

QSC_EXPORT_API qsc_tls_status qsc_tls_engine_initialize_server	(	qsc_tls_connection *	connection,
		const qsc_tls_server_config *	config )

Initialize a TLS engine connection as a server.

Initializes the supplied connection object for server-side TLS operation using the caller-provided server configuration. The function clears and prepares the connection state, selects the server role, and initializes the embedded server protocol context.

Parameters

connection	[qsc_tls_connection*] Pointer to the TLS engine connection context to initialize.
config	[const qsc_tls_server_config*] Pointer to the server configuration used to initialize the server protocol state.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success, or an error status on invalid input or initialization failure.

qsc_tls_engine_is_handshake_complete()

QSC_EXPORT_API bool qsc_tls_engine_is_handshake_complete

(

const qsc_tls_connection *

connection

)

Test whether the TLS handshake is complete.

Returns the handshake-completion status of the active client or server state. When this function returns true, the connection may send and receive protected application data.

Parameters

connection

[const qsc_tls_connection*] Pointer to an initialized TLS engine connection.

Returns

[bool] Returns true when the handshake is complete; otherwise returns false.

qsc_tls_engine_read_application_data()

QSC_EXPORT_API qsc_tls_status qsc_tls_engine_read_application_data	(	qsc_tls_connection *	connection,
		const uint8_t *	input,
		size_t	inlen,
		size_t *	consumed,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written )

Decrypt inbound application records.

Consumes inbound TLS records, decrypts application-data records under the active read traffic keys, and writes plaintext application bytes to the output buffer. The function reports the number of inbound bytes consumed and plaintext bytes written.

Parameters

connection	[qsc_tls_connection*] Pointer to an established TLS engine connection.
input	[const uint8_t*] Pointer to inbound TLS record bytes.
inlen	[size_t] Number of inbound bytes available in input.
consumed	[size_t*] Pointer receiving the number of inbound bytes consumed.
output	[uint8_t*] Pointer to the plaintext output buffer.
outlen	[size_t] Size, in bytes, of the plaintext output buffer.
written	[size_t*] Pointer receiving the number of plaintext bytes written to output.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success, or an error status on invalid state, malformed records, authentication failure, insufficient output capacity, or closure alert processing.

qsc_tls_engine_read_application_data_ex()

QSC_EXPORT_API qsc_tls_status qsc_tls_engine_read_application_data_ex	(	qsc_tls_connection *	connection,
		const uint8_t *	input,
		size_t	inlen,
		size_t *	consumed,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written,
		uint8_t *	responseoutput,
		size_t	responseoutlen,
		size_t *	responsewritten )

Decrypt inbound records and process post-handshake messages.

Consumes inbound TLS records, decrypts application-data records, and dispatches supported post-handshake handshake messages such as KeyUpdate. If an inbound KeyUpdate requests a reciprocal update, the generated response record is written to responseoutput when a response buffer is supplied.

Parameters

connection	[qsc_tls_connection*] Pointer to an established TLS engine connection.
input	[const uint8_t*] Pointer to inbound TLS record bytes.
inlen	[size_t] Number of inbound bytes available in input.
consumed	[size_t*] Pointer receiving the number of inbound bytes consumed.
output	[uint8_t*] Pointer to the plaintext application output buffer.
outlen	[size_t] Size, in bytes, of the plaintext output buffer.
written	[size_t*] Pointer receiving the number of plaintext bytes written to output.
responseoutput	[uint8_t*] Optional pointer to a buffer receiving any automatically generated post-handshake response records.
responseoutlen	[size_t] Size, in bytes, of responseoutput when non-NULL.
responsewritten	[size_t*] Optional pointer receiving the number of bytes written to responseoutput.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success, or an error status on invalid state, malformed records, authentication failure, unsupported post-handshake input, or insufficient buffer capacity.

qsc_tls_engine_request_key_update()

QSC_EXPORT_API qsc_tls_status qsc_tls_engine_request_key_update	(	qsc_tls_connection *	connection,
		bool	requestpeerupdate,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written )

Initiate a TLS 1.3 KeyUpdate operation.

Builds and encrypts a KeyUpdate post-handshake record using the active application write traffic keys, advances the local write traffic secret, and writes the resulting record to the caller-supplied output buffer.

Parameters

connection	[qsc_tls_connection*] Pointer to an established TLS engine connection.
requestpeerupdate	[bool] If true, request that the peer also update its sending keys.
output	[uint8_t*] Pointer to the output buffer receiving the encrypted KeyUpdate record.
outlen	[size_t] Size, in bytes, of the output buffer.
written	[size_t*] Pointer receiving the number of bytes written to output.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success, or an error status on invalid state, insufficient output capacity, or cryptographic failure.

qsc_tls_engine_write_application_data()

QSC_EXPORT_API qsc_tls_status qsc_tls_engine_write_application_data	(	qsc_tls_connection *	connection,
		const uint8_t *	input,
		size_t	inlen,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written )

Encrypt and frame application data.

Encrypts plaintext application data under the active application write traffic keys and writes one or more TLS application-data records to the output buffer. The handshake must be complete before application data is written.

Parameters

connection	[qsc_tls_connection*] Pointer to an established TLS engine connection.
input	[const uint8_t*] Pointer to plaintext application data.
inlen	[size_t] Number of plaintext bytes to encrypt.
output	[uint8_t*] Pointer to the caller-supplied output buffer.
outlen	[size_t] Size, in bytes, of the output buffer.
written	[size_t*] Pointer receiving the number of encrypted record bytes written to output.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success, or an error status on invalid state, invalid input, insufficient output capacity, or encryption failure.