tlssocket.h File Reference

High-level blocking and concurrent socket integration layer for QSC TLS 1.3 and X.509. More...

#include "qsccommon.h"
#include "async.h"
#include "tlsengine.h"
#include "tlssignerdefault.h"
#include "tlsio.h"
#include "socketbase.h"
#include "socketclient.h"
#include "socketserver.h"
#include "x509wrap.h"
#include "x509types.h"

Go to the source code of this file.

Data Structures
struct	qsc_tls_socket_options
	The socket and timeout configuration used by TLS socket contexts, listeners, and connections. More...
struct	qsc_tls_socket_ticket_policy
	The session ticket policy used by TLS socket client and server operations. More...
struct	qsc_tls_socket_result
	A structured result containing wrapper, TLS, socket, X.509, verification, and alert status values. More...
struct	qsc_tls_socket_peer_info
	The peer identity and negotiated-parameter summary exposed by the TLS socket wrapper. More...
struct	qsc_tls_socket_context
	A reusable TLS socket policy, trust, identity, and logging context. More...
struct	qsc_tls_socket_connection
	A live TLS socket connection containing the socket, TLS engine, I/O adapter, and connection state. More...
struct	qsc_tls_socket_listener
	A TLS socket listener that owns a listening socket and references a TLS socket context. More...
struct	qsc_tls_socket_server_worker_state
	The fixed-pool worker state used by the concurrent TLS socket server. More...
struct	qsc_tls_socket_server
	A blocking or concurrent TLS socket server using a fixed connection pool. More...

Macros
#define	QSC_TLS_SOCKET_CIPHER_SUITE_MAX   8U
	The maximum number of cipher suites stored in a TLS socket context preference list.
#define	QSC_TLS_SOCKET_GROUP_MAX   16U
	The maximum number of named groups stored in a TLS socket context preference list.
#define	QSC_TLS_SOCKET_SIGNATURE_SCHEME_MAX   16U
	The maximum number of signature schemes stored in a TLS socket context preference list.
#define	QSC_TLS_SOCKET_SERVER_IDENTITY_MAX   QSC_TLS_MAX_SERVER_IDENTITIES
	The maximum number of SNI-selectable server identities stored in a TLS socket context.
#define	QSC_TLS_SOCKET_ALPN_PROTOCOL_MAX   QSC_TLS_MAX_ALPN_PROTOCOLS
	The maximum number of ALPN protocol identifiers stored in a TLS socket context.
#define	QSC_TLS_SOCKET_ALPN_SIZE_MAX   QSC_TLS_MAX_ALPN_SIZE
	The maximum ALPN protocol identifier length stored in a TLS socket context.
#define	QSC_TLS_SOCKET_SERVER_BUFFER_SIZE   16384U
	The default per-connection application receive buffer size used by the blocking server loop.
#define	QSC_TLS_SOCKET_SERVER_CONNECTIONS_MAX   64U
	The maximum number of fixed connection slots available to the concurrent server mode.
#define	QSC_TLS_SOCKET_FRAME_HEADER_SIZE   4U
	The size in bytes of the length prefix used by the framed application-message API.
#define	QSC_TLS_SOCKET_FRAME_SIZE_MAX   16777216U
	The maximum payload size in bytes accepted by the framed application-message API.
#define	QSC_TLS_SOCKET_TICKET_LIFETIME_MAX   604800U
	The maximum accepted TLS session-ticket lifetime in seconds.

Typedefs
typedef enum qsc_tls_socket_log_level	qsc_tls_socket_log_level
typedef enum qsc_tls_socket_event	qsc_tls_socket_event
typedef struct qsc_tls_socket_options	qsc_tls_socket_options
typedef struct qsc_tls_socket_ticket_policy	qsc_tls_socket_ticket_policy
typedef enum qsc_tls_socket_status	qsc_tls_socket_status
typedef struct qsc_tls_socket_result	qsc_tls_socket_result
typedef void(*	qsc_tls_socket_log_callback) (qsc_tls_socket_log_level level, qsc_tls_socket_event event, const qsc_tls_socket_result *result, const char *message, void *state)
	The TLS socket structured logging callback prototype.
typedef struct qsc_tls_socket_peer_info	qsc_tls_socket_peer_info
typedef struct qsc_tls_socket_context	qsc_tls_socket_context
typedef struct qsc_tls_socket_connection	qsc_tls_socket_connection
typedef struct qsc_tls_socket_listener	qsc_tls_socket_listener
typedef struct qsc_tls_socket_server_worker_state	qsc_tls_socket_server_worker_state
typedef void(*	qsc_tls_socket_server_connect_callback) (qsc_tls_socket_connection *connection, void *state)
	The TLS socket server connect callback prototype.
typedef void(*	qsc_tls_socket_server_receive_callback) (qsc_tls_socket_connection *connection, const uint8_t *message, size_t msglen, void *state)
	The TLS socket server receive callback prototype.
typedef void(*	qsc_tls_socket_server_disconnect_callback) (qsc_tls_socket_connection *connection, void *state)
	The TLS socket server disconnect callback prototype.
typedef void(*	qsc_tls_socket_server_error_callback) (qsc_tls_socket_connection *connection, qsc_tls_socket_status status, void *state)
	The TLS socket server error callback prototype.
typedef struct qsc_tls_socket_server	qsc_tls_socket_server

Enumerations
enum	qsc_tls_socket_log_level {   qsc_tls_socket_log_level_none = 0 , qsc_tls_socket_log_level_error = 1 , qsc_tls_socket_log_level_warning = 2 , qsc_tls_socket_log_level_info = 3 ,   qsc_tls_socket_log_level_debug = 4 }
	The TLS socket wrapper structured logging severity levels. More...
enum	qsc_tls_socket_event {   qsc_tls_socket_event_none = 0 , qsc_tls_socket_event_context_configured = 1 , qsc_tls_socket_event_socket_options = 2 , qsc_tls_socket_event_connect = 3 ,   qsc_tls_socket_event_accept = 4 , qsc_tls_socket_event_handshake_start = 5 , qsc_tls_socket_event_handshake_complete = 6 , qsc_tls_socket_event_send = 7 ,   qsc_tls_socket_event_receive = 8 , qsc_tls_socket_event_frame_send = 9 , qsc_tls_socket_event_frame_receive = 10 , qsc_tls_socket_event_ticket = 11 ,   qsc_tls_socket_event_key_update = 12 , qsc_tls_socket_event_shutdown = 13 , qsc_tls_socket_event_worker_start = 14 , qsc_tls_socket_event_worker_stop = 15 ,   qsc_tls_socket_event_error = 16 }
	The TLS socket wrapper structured logging event identifiers. More...
enum	qsc_tls_socket_status {   qsc_tls_socket_status_success = 0 , qsc_tls_socket_status_invalid_input = 1 , qsc_tls_socket_status_not_initialized = 2 , qsc_tls_socket_status_socket_start_failed = 3 ,   qsc_tls_socket_status_socket_connect_failed = 4 , qsc_tls_socket_status_socket_bind_failed = 5 , qsc_tls_socket_status_socket_listen_failed = 6 , qsc_tls_socket_status_socket_accept_failed = 7 ,   qsc_tls_socket_status_tls_initialize_failed = 8 , qsc_tls_socket_status_tls_handshake_failed = 9 , qsc_tls_socket_status_certificate_load_failed = 10 , qsc_tls_socket_status_certificate_verify_failed = 11 ,   qsc_tls_socket_status_private_key_invalid = 12 , qsc_tls_socket_status_policy_rejected = 13 , qsc_tls_socket_status_io_failed = 14 , qsc_tls_socket_status_closed = 15 ,   qsc_tls_socket_status_internal_error = 16 }
	The TLS socket wrapper status codes. More...

Functions
QSC_EXPORT_API void	qsc_tls_socket_result_clear (qsc_tls_socket_result *result)
	Clear a TLS socket structured result.
QSC_EXPORT_API const char *	qsc_tls_socket_status_string (qsc_tls_socket_status status)
	Return a constant string for a TLS socket wrapper status value.
QSC_EXPORT_API void	qsc_tls_socket_options_initialize_default (qsc_tls_socket_options *options)
	Initialize socket options to the wrapper default values.
QSC_EXPORT_API void	qsc_tls_socket_ticket_policy_initialize_default (qsc_tls_socket_ticket_policy *policy)
	Initialize a session ticket policy to the wrapper default values.
QSC_EXPORT_API void	qsc_tls_socket_context_initialize (qsc_tls_socket_context *context)
	Initialize a reusable TLS socket context.
QSC_EXPORT_API void	qsc_tls_socket_context_dispose (qsc_tls_socket_context *context)
	Dispose of a TLS socket context and clear owned sensitive state.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_default_client_policy (qsc_tls_socket_context *context)
	Configure the context with the default TLS 1.3 client interoperability policy.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_default_server_policy (qsc_tls_socket_context *context)
	Configure the context with the default TLS 1.3 server interoperability policy.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_mlkem_hybrid_policy (qsc_tls_socket_context *context)
	Configure the context with an explicit ML-KEM hybrid interoperability policy.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_experimental_pqc_policy (qsc_tls_socket_context *context)
	Configure the context with the experimental ML-KEM and ML-DSA policy.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_strict_policy (qsc_tls_socket_context *context)
	Configure the context with the strict TLS policy.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_development_policy (qsc_tls_socket_context *context)
	Configure the context with the development TLS policy.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_cipher_suites (qsc_tls_socket_context *context, const qsc_tls_cipher_suite *suites, size_t suitecount)
	Set the ordered cipher suite preference list for the context.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_named_groups (qsc_tls_socket_context *context, const qsc_tls_named_group *groups, size_t groupcount)
	Set the ordered named group preference list for the context.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_signature_schemes (qsc_tls_socket_context *context, const qsc_tls_signature_scheme *schemes, size_t schemecount)
	Set the ordered signature scheme preference list for the context.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_load_trust_anchor_file (qsc_tls_socket_context *context, const char *path, bool selfsigned)
	Load a trust anchor certificate file into the context trust store.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_load_trust_anchor_bundle_file (qsc_tls_socket_context *context, const char *path, bool selfsigned)
	Load a trust anchor bundle file into the context trust store.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_load_crl_file (qsc_tls_socket_context *context, const char *path)
	Load a certificate revocation list file into the context trust store.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_load_server_identity_files (qsc_tls_socket_context *context, const char *certificatechainpath, const char *privatekeypath, qsc_tls_signature_scheme verifyscheme)
	Load a server certificate chain and private key into the context.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_add_server_identity_files (qsc_tls_socket_context *context, const char *hostname, const char *certificatechainpath, const char *privatekeypath, qsc_tls_signature_scheme verifyscheme)
	Load an additional SNI-selectable server identity from certificate-chain and private-key files.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_sni_required (qsc_tls_socket_context *context, bool required)
	Configure whether server handshakes require a recognized SNI hostname.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_client_auth (qsc_tls_socket_context *context, bool requestclientauth, bool requireclientauth)
	Configure server-side client certificate authentication policy.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_client_authorization (qsc_tls_socket_context *context, qsc_tls_client_authorization_callback callback, void *state, bool required)
	Configure the server-side mTLS application authorization callback.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_socket_options (qsc_tls_socket_context *context, const qsc_tls_socket_options *options)
	Set the default socket options for the context.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_alpn_protocols (qsc_tls_socket_context *context, const char *const *protocols, size_t protocolcount, bool required)
	Set the ordered ALPN protocol list for the context.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_clear_alpn_protocols (qsc_tls_socket_context *context)
	Clear the ordered ALPN protocol list from the context.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_log_callback (qsc_tls_socket_context *context, qsc_tls_socket_log_callback callback, void *state)
	Set the context-level structured logging callback.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_session_ticket_policy (qsc_tls_socket_context *context, const qsc_tls_socket_ticket_policy *policy)
	Set the context-level session ticket policy.
QSC_EXPORT_API bool	qsc_tls_socket_session_ticket_is_valid (const qsc_tls_session_ticket *ticket)
	Test whether a session ticket is structurally acceptable for resumption.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_context_set_session_ticket (qsc_tls_socket_context *context, const qsc_tls_session_ticket *ticket)
	Set the client session ticket used for resumption attempts.
QSC_EXPORT_API void	qsc_tls_socket_context_clear_session_ticket (qsc_tls_socket_context *context)
	Clear the client session ticket stored in the context.
QSC_EXPORT_API void	qsc_tls_socket_connection_initialize (qsc_tls_socket_connection *connection)
	Initialize a TLS socket connection structure.
QSC_EXPORT_API void	qsc_tls_socket_connection_dispose (qsc_tls_socket_connection *connection)
	Dispose of a TLS socket connection and clear owned sensitive state.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_client_connect_host (qsc_tls_socket_connection *connection, const qsc_tls_socket_context *context, const char *hostname, const char *service)
	Connect to a remote host and complete a TLS client handshake.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_client_connect_host_ex (qsc_tls_socket_connection *connection, const qsc_tls_socket_context *context, const char *hostname, const char *service, const qsc_tls_session_ticket *ticket, bool enableearlydata)
	Connect to a remote host with an explicit session ticket and early-data preference.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_client_connect_ipv4 (qsc_tls_socket_connection *connection, const qsc_tls_socket_context *context, const qsc_ipinfo_ipv4_address *address, uint16_t port, const char *hostname)
	Connect to an IPv4 address and complete a TLS client handshake.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_client_connect_ipv6 (qsc_tls_socket_connection *connection, const qsc_tls_socket_context *context, const qsc_ipinfo_ipv6_address *address, uint16_t port, const char *hostname)
	Connect to an IPv6 address and complete a TLS client handshake.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_send (qsc_tls_socket_connection *connection, const uint8_t *input, size_t inlen, size_t *written)
	Send application data over a completed TLS socket connection.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_receive (qsc_tls_socket_connection *connection, uint8_t *output, size_t outlen, size_t *read)
	Receive application data from a completed TLS socket connection.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_shutdown (qsc_tls_socket_connection *connection)
	Send a TLS close_notify alert and close the TLS socket connection.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_key_update (qsc_tls_socket_connection *connection, bool requestpeerupdate)
	Request a TLS 1.3 KeyUpdate operation on a completed connection.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_server_send_session_ticket (qsc_tls_socket_connection *connection, uint32_t lifetime_seconds, qsc_tls_session_ticket *ticketout)
	Send a TLS server session ticket over a completed server connection.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_connection_set_socket_options (qsc_tls_socket_connection *connection, const qsc_tls_socket_options *options)
	Apply socket options to an initialized or connected TLS socket connection.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_connection_set_log_callback (qsc_tls_socket_connection *connection, qsc_tls_socket_log_callback callback, void *state)
	Set the connection-level structured logging callback.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_connection_cancel (qsc_tls_socket_connection *connection)
	Request cancellation of a TLS socket connection.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_get_peer_info (const qsc_tls_socket_connection *connection, qsc_tls_socket_peer_info *peerinfo)
	Retrieve the peer information summary for a TLS socket connection.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_get_selected_alpn (const qsc_tls_socket_connection *connection, char *protocol, size_t protocolcap, size_t *protocollen)
	Retrieve the selected ALPN protocol for a TLS socket connection.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_connection_get_session_ticket (const qsc_tls_socket_connection *connection, qsc_tls_session_ticket *ticketout)
	Retrieve the most recent session ticket associated with a connection.
QSC_EXPORT_API void	qsc_tls_socket_connection_clear_session_ticket (qsc_tls_socket_connection *connection)
	Clear the most recent session ticket retained by a connection.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_send_frame (qsc_tls_socket_connection *connection, const uint8_t *input, size_t inlen)
	Send a length-prefixed framed application message.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_receive_frame (qsc_tls_socket_connection *connection, uint8_t *output, size_t outlen, size_t *read)
	Receive a length-prefixed framed application message.
QSC_EXPORT_API bool	qsc_tls_socket_is_connected (const qsc_tls_socket_connection *connection)
	Test whether a TLS socket connection owns a connected socket.
QSC_EXPORT_API bool	qsc_tls_socket_is_handshake_complete (const qsc_tls_socket_connection *connection)
	Test whether the TLS handshake has completed.
QSC_EXPORT_API qsc_tls_cipher_suite	qsc_tls_socket_negotiated_cipher_suite (const qsc_tls_socket_connection *connection)
	Get the negotiated TLS cipher suite.
QSC_EXPORT_API qsc_tls_named_group	qsc_tls_socket_negotiated_group (const qsc_tls_socket_connection *connection)
	Get the negotiated TLS named group.
QSC_EXPORT_API qsc_tls_signature_scheme	qsc_tls_socket_negotiated_signature_scheme (const qsc_tls_socket_connection *connection)
	Get the negotiated TLS signature scheme.
QSC_EXPORT_API void	qsc_tls_socket_listener_initialize (qsc_tls_socket_listener *listener)
	Initialize a TLS socket listener structure.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_listener_set_options (qsc_tls_socket_listener *listener, bool reuseaddress, bool nodelay, uint32_t recvtimeoutms, uint32_t sendtimeoutms)
	Set basic listener socket options.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_listener_set_socket_options (qsc_tls_socket_listener *listener, const qsc_tls_socket_options *options)
	Set the full listener socket option structure.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_listener_bind (qsc_tls_socket_listener *listener, const qsc_tls_socket_context *context, const char *address, uint16_t port, qsc_socket_address_families family)
	Bind a TLS listener to a local address and port.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_listener_accept (qsc_tls_socket_listener *listener, qsc_tls_socket_connection *connection)
	Accept an inbound socket and complete a TLS server handshake.
QSC_EXPORT_API void	qsc_tls_socket_listener_close (qsc_tls_socket_listener *listener)
	Close a TLS socket listener.
QSC_EXPORT_API void	qsc_tls_socket_server_initialize (qsc_tls_socket_server *server)
	Initialize a TLS socket server structure.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_server_configure (qsc_tls_socket_server *server, const qsc_tls_socket_context *context, const char *address, uint16_t port, qsc_socket_address_families family)
	Configure a TLS socket server listener and context.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_server_set_callbacks (qsc_tls_socket_server *server, qsc_tls_socket_server_connect_callback onconnect, qsc_tls_socket_server_receive_callback onreceive, qsc_tls_socket_server_disconnect_callback ondisconnect, qsc_tls_socket_server_error_callback onerror, void *state)
	Set the application callbacks for a TLS socket server.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_server_set_log_callback (qsc_tls_socket_server *server, qsc_tls_socket_log_callback callback, void *state)
	Set the server-level structured logging callback.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_server_set_max_clients (qsc_tls_socket_server *server, size_t maxclients)
	Set the maximum number of concurrent client connections accepted by the server.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_server_start (qsc_tls_socket_server *server)
	Start the server in blocking sequential mode.
QSC_EXPORT_API qsc_tls_socket_status	qsc_tls_socket_server_start_concurrent (qsc_tls_socket_server *server)
	Start the server in bounded concurrent mode.
QSC_EXPORT_API void	qsc_tls_socket_server_stop (qsc_tls_socket_server *server)
	Stop a running TLS socket server.
QSC_EXPORT_API void	qsc_tls_socket_server_dispose (qsc_tls_socket_server *server)
	Dispose of a TLS socket server and clear owned connection state.

Detailed Description

High-level blocking and concurrent socket integration layer for QSC TLS 1.3 and X.509.

This header defines the public API for the QSC TLS socket wrapper. The wrapper composes the QSC dual-stack socket layer, the TLS 1.3 engine, the record-framed TLS I/O adapter, and the X.509 wrapper into deployment-oriented client, listener, accepted-connection, and server APIs.

The wrapper does not implement an independent TLS or X.509 stack. It owns the application-facing lifecycle around the existing TLS and X.509 components. It provides context-based policy selection, trust-store loading, server identity loading, socket option control, blocking client connections, blocking listener accept, a bounded concurrent server mode, framed application messages, session ticket policy helpers, structured result reporting, and optional structured logging callbacks.

The default client and server policies are intended for conservative TLS 1.3 interoperability. The ML-KEM hybrid and experimental PQC profiles are explicit opt-in profiles and require compatible peers. The wrapper stores TLS, socket, and X.509 status values separately in qsc_tls_socket_result so that callers can distinguish transport failures from TLS protocol and certificate validation errors.

Ownership model:

• qsc_tls_socket_context owns reusable policy, trust-store, X.509 bridge, server identity, and session ticket policy state.
• qsc_tls_socket_connection owns a connected or accepted socket, a TLS engine instance, and a TLS I/O adapter bound to that engine and socket.
• qsc_tls_socket_listener owns the listening socket and references a context supplied by the caller.
• qsc_tls_socket_server owns a listener and, in concurrent mode, a fixed pool of connection slots.

// Minimal client usage.
qsc_tls_socket_context ctx;
qsc_tls_socket_connection conn;
uint8_t buf[4096U];
size_t rlen = 0U;
 
qsc_tls_socket_context_initialize(&ctx);
qsc_tls_socket_context_set_default_client_policy(&ctx);
qsc_tls_socket_context_load_trust_anchor_bundle_file(&ctx, "ca-bundle.pem", true);
 
qsc_tls_socket_connection_initialize(&conn);
 
if (qsc_tls_socket_client_connect_host(&conn, &ctx, "example.com", "443") == qsc_tls_socket_status_success)
{
    const uint8_t req[] = "GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n";
    qsc_tls_socket_send(&conn, req, sizeof(req) - 1U, NULL);
    qsc_tls_socket_receive(&conn, buf, sizeof(buf), &rlen);
    qsc_tls_socket_shutdown(&conn);
}
 
qsc_tls_socket_connection_dispose(&conn);
qsc_tls_socket_context_dispose(&ctx);

Reference Links:

• RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3
• RFC 5280: Internet X.509 Public Key Infrastructure Certificate and CRL Profile
• RFC 6066: TLS Extension Definitions
• RFC 7301: TLS Application-Layer Protocol Negotiation Extension

Typedef Documentation

qsc_tls_socket_log_callback

typedef void(* qsc_tls_socket_log_callback) (qsc_tls_socket_log_level level, qsc_tls_socket_event event, const qsc_tls_socket_result *result, const char *message, void *state)

The TLS socket structured logging callback prototype.

Parameters

level	[enum] The logging severity level.
event	[enum] The event identifier.
result	[const struct*] A pointer to the structured result associated with the event.
message	[const char*] A null-terminated event description string.
state	[void*] The user-defined callback state pointer.

qsc_tls_socket_server_connect_callback

typedef void(* qsc_tls_socket_server_connect_callback) (qsc_tls_socket_connection *connection, void *state)

The TLS socket server connect callback prototype.

Parameters

connection	[struct*] A pointer to the established TLS socket connection.
state	[void*] The user-defined callback state pointer.

qsc_tls_socket_server_disconnect_callback

typedef void(* qsc_tls_socket_server_disconnect_callback) (qsc_tls_socket_connection *connection, void *state)

The TLS socket server disconnect callback prototype.

Parameters

connection	[struct*] A pointer to the TLS socket connection being disconnected.
state	[void*] The user-defined callback state pointer.

qsc_tls_socket_server_error_callback

typedef void(* qsc_tls_socket_server_error_callback) (qsc_tls_socket_connection *connection, qsc_tls_socket_status status, void *state)

The TLS socket server error callback prototype.

Parameters

connection	[struct*] A pointer to the TLS socket connection associated with the error, when available.
status	[enum] The wrapper status value associated with the error.
state	[void*] The user-defined callback state pointer.

qsc_tls_socket_server_receive_callback

typedef void(* qsc_tls_socket_server_receive_callback) (qsc_tls_socket_connection *connection, const uint8_t *message, size_t msglen, void *state)

The TLS socket server receive callback prototype.

Parameters

connection	[struct*] A pointer to the established TLS socket connection.
message	[const uint8_t*] A pointer to the received application data.
msglen	[size_t] The length of the received application data in bytes.
state	[void*] The user-defined callback state pointer.

Enumeration Type Documentation

qsc_tls_socket_event

enum qsc_tls_socket_event

The TLS socket wrapper structured logging event identifiers.

Enumerator
qsc_tls_socket_event_none	No event is assigned.
qsc_tls_socket_event_context_configured	The TLS socket context policy or settings were configured.
qsc_tls_socket_event_socket_options	Socket options or timeout settings were applied.
qsc_tls_socket_event_connect	A client socket connection attempt was performed.
qsc_tls_socket_event_accept	A server listener accepted an inbound socket.
qsc_tls_socket_event_handshake_start	A TLS handshake was started.
qsc_tls_socket_event_handshake_complete	A TLS handshake completed successfully.
qsc_tls_socket_event_send	TLS application data was sent.
qsc_tls_socket_event_receive	TLS application data was received.
qsc_tls_socket_event_frame_send	A framed application message was sent.
qsc_tls_socket_event_frame_receive	A framed application message was received.
qsc_tls_socket_event_ticket	A TLS session ticket operation was performed.
qsc_tls_socket_event_key_update	A TLS KeyUpdate operation was performed.
qsc_tls_socket_event_shutdown	A TLS socket shutdown operation was performed.
qsc_tls_socket_event_worker_start	A concurrent server worker started.
qsc_tls_socket_event_worker_stop	A concurrent server worker stopped.
qsc_tls_socket_event_error	A generic TLS socket wrapper error occurred.

qsc_tls_socket_log_level

enum qsc_tls_socket_log_level

The TLS socket wrapper structured logging severity levels.

Enumerator
qsc_tls_socket_log_level_none	No logging severity is assigned.
qsc_tls_socket_log_level_error	An error event occurred.
qsc_tls_socket_log_level_warning	A non-fatal warning event occurred.
qsc_tls_socket_log_level_info	An informational lifecycle event occurred.
qsc_tls_socket_log_level_debug	A diagnostic event occurred.

qsc_tls_socket_status

enum qsc_tls_socket_status

The TLS socket wrapper status codes.

Enumerator
qsc_tls_socket_status_success	The operation completed successfully.
qsc_tls_socket_status_invalid_input	One or more input parameters were invalid.
qsc_tls_socket_status_not_initialized	The requested object was not initialized.
qsc_tls_socket_status_socket_start_failed	Socket subsystem initialization failed.
qsc_tls_socket_status_socket_connect_failed	The socket connect operation failed.
qsc_tls_socket_status_socket_bind_failed	The socket bind operation failed.
qsc_tls_socket_status_socket_listen_failed	The socket listen operation failed.
qsc_tls_socket_status_socket_accept_failed	The socket accept operation failed.
qsc_tls_socket_status_tls_initialize_failed	TLS engine initialization failed.
qsc_tls_socket_status_tls_handshake_failed	The TLS handshake failed.
qsc_tls_socket_status_certificate_load_failed	Certificate, private key, trust anchor, or CRL loading failed.
qsc_tls_socket_status_certificate_verify_failed	Certificate verification failed.
qsc_tls_socket_status_private_key_invalid	The configured private key was invalid or incompatible.
qsc_tls_socket_status_policy_rejected	The configured TLS policy was rejected or unsupported.
qsc_tls_socket_status_io_failed	A TLS or socket I/O operation failed.
qsc_tls_socket_status_closed	The connection was closed or cancelled.
qsc_tls_socket_status_internal_error	An internal wrapper error occurred.

Function Documentation

qsc_tls_socket_client_connect_host()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_client_connect_host	(	qsc_tls_socket_connection *	connection,
		const qsc_tls_socket_context *	context,
		const char *	hostname,
		const char *	service )

Connect to a remote host and complete a TLS client handshake.

Parameters

connection	[struct*] A pointer to an initialized connection structure.
context	[const struct*] A pointer to an initialized client context.
hostname	[const char*] The null-terminated DNS hostname used for connection and verification.
service	[const char*] The null-terminated service or port string.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_client_connect_host_ex()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_client_connect_host_ex	(	qsc_tls_socket_connection *	connection,
		const qsc_tls_socket_context *	context,
		const char *	hostname,
		const char *	service,
		const qsc_tls_session_ticket *	ticket,
		bool	enableearlydata )

Connect to a remote host with an explicit session ticket and early-data preference.

Parameters

connection	[struct*] A pointer to an initialized connection structure.
context	[const struct*] A pointer to an initialized client context.
hostname	[const char*] The null-terminated DNS hostname used for connection and verification.
service	[const char*] The null-terminated service or port string.
ticket	[const struct*] A pointer to the session ticket to offer, or NULL for a full handshake.
enableearlydata	[bool] Enable early data if the ticket and peer support it.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_client_connect_ipv4()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_client_connect_ipv4	(	qsc_tls_socket_connection *	connection,
		const qsc_tls_socket_context *	context,
		const qsc_ipinfo_ipv4_address *	address,
		uint16_t	port,
		const char *	hostname )

Connect to an IPv4 address and complete a TLS client handshake.

Parameters

connection	[struct*] A pointer to an initialized connection structure.
context	[const struct*] A pointer to an initialized client context.
address	[const struct*] A pointer to the IPv4 address.
port	[uint16_t] The remote TCP port.
hostname	[const char*] The verification hostname, or NULL when policy permits.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_client_connect_ipv6()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_client_connect_ipv6	(	qsc_tls_socket_connection *	connection,
		const qsc_tls_socket_context *	context,
		const qsc_ipinfo_ipv6_address *	address,
		uint16_t	port,
		const char *	hostname )

Connect to an IPv6 address and complete a TLS client handshake.

Parameters

connection	[struct*] A pointer to an initialized connection structure.
context	[const struct*] A pointer to an initialized client context.
address	[const struct*] A pointer to the IPv6 address.
port	[uint16_t] The remote TCP port.
hostname	[const char*] The verification hostname, or NULL when policy permits.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_connection_cancel()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_connection_cancel

(

qsc_tls_socket_connection *

connection

)

Request cancellation of a TLS socket connection.

Parameters

connection

[struct*] A pointer to the TLS socket connection.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_connection_clear_session_ticket()

QSC_EXPORT_API void qsc_tls_socket_connection_clear_session_ticket

(

qsc_tls_socket_connection *

connection

)

Clear the most recent session ticket retained by a connection.

Parameters

connection

[struct*] A pointer to the TLS socket connection.

qsc_tls_socket_connection_dispose()

QSC_EXPORT_API void qsc_tls_socket_connection_dispose

(

qsc_tls_socket_connection *

connection

)

Dispose of a TLS socket connection and clear owned sensitive state.

Parameters

connection

[struct*] A pointer to the connection structure to dispose.

qsc_tls_socket_connection_get_session_ticket()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_connection_get_session_ticket	(	const qsc_tls_socket_connection *	connection,
		qsc_tls_session_ticket *	ticketout )

Retrieve the most recent session ticket associated with a connection.

Parameters

connection	[const struct*] A pointer to the TLS socket connection.
ticketout	[struct*] A pointer to the ticket structure to receive the ticket copy.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_connection_initialize()

QSC_EXPORT_API void qsc_tls_socket_connection_initialize

(

qsc_tls_socket_connection *

connection

)

Initialize a TLS socket connection structure.

Parameters

connection

[struct*] A pointer to the connection structure to initialize.

qsc_tls_socket_connection_set_log_callback()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_connection_set_log_callback	(	qsc_tls_socket_connection *	connection,
		qsc_tls_socket_log_callback	callback,
		void *	state )

Set the connection-level structured logging callback.

Parameters

connection	[struct*] A pointer to the TLS socket connection.
callback	[function] The logging callback pointer, or NULL to disable connection logging.
state	[void*] The user-defined callback state pointer.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_connection_set_socket_options()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_connection_set_socket_options	(	qsc_tls_socket_connection *	connection,
		const qsc_tls_socket_options *	options )

Apply socket options to an initialized or connected TLS socket connection.

Parameters

connection	[struct*] A pointer to the TLS socket connection.
options	[const struct*] A pointer to the socket options to apply.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_add_server_identity_files()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_add_server_identity_files	(	qsc_tls_socket_context *	context,
		const char *	hostname,
		const char *	certificatechainpath,
		const char *	privatekeypath,
		qsc_tls_signature_scheme	verifyscheme )

Load an additional SNI-selectable server identity from certificate-chain and private-key files.

Parameters

context	[struct*] A pointer to the initialized context.
hostname	[const char*] The DNS name or wildcard pattern used for SNI selection.
certificatechainpath	[const char*] The certificate-chain file path.
privatekeypath	[const char*] The private-key file path.
verifyscheme	[enum] The TLS CertificateVerify signature scheme for the identity.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_clear_alpn_protocols()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_clear_alpn_protocols

(

qsc_tls_socket_context *

context

)

Clear the ordered ALPN protocol list from the context.

Parameters

context

[struct*] A pointer to the initialized context.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_clear_session_ticket()

QSC_EXPORT_API void qsc_tls_socket_context_clear_session_ticket

(

qsc_tls_socket_context *

context

)

Clear the client session ticket stored in the context.

Parameters

context

[struct*] A pointer to the initialized context.

qsc_tls_socket_context_dispose()

QSC_EXPORT_API void qsc_tls_socket_context_dispose

(

qsc_tls_socket_context *

context

)

Dispose of a TLS socket context and clear owned sensitive state.

Parameters

context

[struct*] A pointer to the context structure to dispose.

qsc_tls_socket_context_initialize()

QSC_EXPORT_API void qsc_tls_socket_context_initialize

(

qsc_tls_socket_context *

context

)

Initialize a reusable TLS socket context.

Parameters

context

[struct*] A pointer to the context structure to initialize.

qsc_tls_socket_context_load_crl_file()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_load_crl_file	(	qsc_tls_socket_context *	context,
		const char *	path )

Load a certificate revocation list file into the context trust store.

Parameters

context	[struct*] A pointer to the initialized context.
path	[const char*] The null-terminated file path to the CRL file.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_load_server_identity_files()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_load_server_identity_files	(	qsc_tls_socket_context *	context,
		const char *	certificatechainpath,
		const char *	privatekeypath,
		qsc_tls_signature_scheme	verifyscheme )

Load a server certificate chain and private key into the context.

Parameters

context	[struct*] A pointer to the initialized context.
certificatechainpath	[const char*] The null-terminated file path to the server certificate chain.
privatekeypath	[const char*] The null-terminated file path to the server private key.
verifyscheme	[enum] The TLS signature scheme used by the server CertificateVerify operation.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_load_trust_anchor_bundle_file()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_load_trust_anchor_bundle_file	(	qsc_tls_socket_context *	context,
		const char *	path,
		bool	selfsigned )

Load a trust anchor bundle file into the context trust store.

Parameters

context	[struct*] A pointer to the initialized context.
path	[const char*] The null-terminated file path to the trust anchor bundle.
selfsigned	[bool] Indicates whether the bundle contains self-signed trust anchors.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_load_trust_anchor_file()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_load_trust_anchor_file	(	qsc_tls_socket_context *	context,
		const char *	path,
		bool	selfsigned )

Load a trust anchor certificate file into the context trust store.

Parameters

context	[struct*] A pointer to the initialized context.
path	[const char*] The null-terminated file path to the trust anchor certificate.
selfsigned	[bool] Indicates whether the trust anchor is self-signed.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_alpn_protocols()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_alpn_protocols	(	qsc_tls_socket_context *	context,
		const char *const *	protocols,
		size_t	protocolcount,
		bool	required )

Set the ordered ALPN protocol list for the context.

Parameters

context	[struct*] A pointer to the initialized context.
protocols	[const char**] A pointer to an ordered list of null-terminated protocol strings.
protocolcount	[size_t] The number of protocol strings in the list.
required	[bool] Require a mutually supported ALPN protocol when true.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_cipher_suites()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_cipher_suites	(	qsc_tls_socket_context *	context,
		const qsc_tls_cipher_suite *	suites,
		size_t	suitecount )

Set the ordered cipher suite preference list for the context.

Parameters

context	[struct*] A pointer to the initialized context.
suites	[const enum*] A pointer to the cipher suite preference array.
suitecount	[size_t] The number of cipher suites in the array.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_client_auth()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_client_auth	(	qsc_tls_socket_context *	context,
		bool	requestclientauth,
		bool	requireclientauth )

Configure server-side client certificate authentication policy.

Parameters

context	[struct*] A pointer to the initialized context.
requestclientauth	[bool] Request a client certificate from peers when true.
requireclientauth	[bool] Require a verified client certificate when true.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_client_authorization()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_client_authorization	(	qsc_tls_socket_context *	context,
		qsc_tls_client_authorization_callback	callback,
		void *	state,
		bool	required )

Configure the server-side mTLS application authorization callback.

The callback is invoked after client-certificate chain validation succeeds. If required is true, the handshake policy rejects a validated client certificate when no callback is configured or when the callback returns false.

Parameters

context	[struct*] The TLS socket context 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_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_default_client_policy()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_default_client_policy

(

qsc_tls_socket_context *

context

)

Configure the context with the default TLS 1.3 client interoperability policy.

Parameters

context

[struct*] A pointer to the initialized context.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_default_server_policy()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_default_server_policy

(

qsc_tls_socket_context *

context

)

Configure the context with the default TLS 1.3 server interoperability policy.

Parameters

context

[struct*] A pointer to the initialized context.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_development_policy()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_development_policy

(

qsc_tls_socket_context *

context

)

Configure the context with the development TLS policy.

The development policy is intended for local testing. It may permit unverified peers depending on the lower TLS and X.509 configuration. It must not be used for production deployments.

Parameters

context

[struct*] A pointer to the initialized context.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_experimental_pqc_policy()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_experimental_pqc_policy

(

qsc_tls_socket_context *

context

)

Configure the context with the experimental ML-KEM and ML-DSA policy.

This policy enables experimental post-quantum key-establishment and signature preferences. It requires a peer that supports the same experimental TLS named groups and signature schemes.

Parameters

context

[struct*] A pointer to the initialized context.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_log_callback()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_log_callback	(	qsc_tls_socket_context *	context,
		qsc_tls_socket_log_callback	callback,
		void *	state )

Set the context-level structured logging callback.

Parameters

context	[struct*] A pointer to the initialized context.
callback	[function] The logging callback pointer, or NULL to disable context logging.
state	[void*] The user-defined callback state pointer.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_mlkem_hybrid_policy()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_mlkem_hybrid_policy

(

qsc_tls_socket_context *

context

)

Configure the context with an explicit ML-KEM hybrid interoperability policy.

The ML-KEM hybrid policy enables the hybrid ML-KEM named-group preference while retaining conventional TLS 1.3 cipher suites and classical certificate signature schemes for peers that support hybrid key establishment.

Parameters

context

[struct*] A pointer to the initialized context.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_named_groups()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_named_groups	(	qsc_tls_socket_context *	context,
		const qsc_tls_named_group *	groups,
		size_t	groupcount )

Set the ordered named group preference list for the context.

Parameters

context	[struct*] A pointer to the initialized context.
groups	[const enum*] A pointer to the named group preference array.
groupcount	[size_t] The number of named groups in the array.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_session_ticket()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_session_ticket	(	qsc_tls_socket_context *	context,
		const qsc_tls_session_ticket *	ticket )

Set the client session ticket used for resumption attempts.

Parameters

context	[struct*] A pointer to the initialized context.
ticket	[const struct*] A pointer to the session ticket to copy into the context.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_session_ticket_policy()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_session_ticket_policy	(	qsc_tls_socket_context *	context,
		const qsc_tls_socket_ticket_policy *	policy )

Set the context-level session ticket policy.

Parameters

context	[struct*] A pointer to the initialized context.
policy	[const struct*] A pointer to the session ticket policy to copy into the context.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_signature_schemes()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_signature_schemes	(	qsc_tls_socket_context *	context,
		const qsc_tls_signature_scheme *	schemes,
		size_t	schemecount )

Set the ordered signature scheme preference list for the context.

Parameters

context	[struct*] A pointer to the initialized context.
schemes	[const enum*] A pointer to the signature scheme preference array.
schemecount	[size_t] The number of signature schemes in the array.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_sni_required()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_sni_required	(	qsc_tls_socket_context *	context,
		bool	required )

Configure whether server handshakes require a recognized SNI hostname.

Parameters

context	[struct*] A pointer to the initialized context.
required	[bool] Set to true to reject absent or unmatched SNI names.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_socket_options()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_socket_options	(	qsc_tls_socket_context *	context,
		const qsc_tls_socket_options *	options )

Set the default socket options for the context.

Parameters

context	[struct*] A pointer to the initialized context.
options	[const struct*] A pointer to the socket options to copy into the context.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_context_set_strict_policy()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_context_set_strict_policy

(

qsc_tls_socket_context *

context

)

Configure the context with the strict TLS policy.

Parameters

context

[struct*] A pointer to the initialized context.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_get_peer_info()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_get_peer_info	(	const qsc_tls_socket_connection *	connection,
		qsc_tls_socket_peer_info *	peerinfo )

Retrieve the peer information summary for a TLS socket connection.

Parameters

connection	[const struct*] A pointer to the TLS socket connection.
peerinfo	[struct*] A pointer to the peer information structure to receive the summary.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_get_selected_alpn()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_get_selected_alpn	(	const qsc_tls_socket_connection *	connection,
		char *	protocol,
		size_t	protocolcap,
		size_t *	protocollen )

Retrieve the selected ALPN protocol for a TLS socket connection.

Parameters

connection	[const struct*] A pointer to the TLS socket connection.
protocol	[char*] A pointer to the destination string buffer.
protocolcap	[size_t] Size, in bytes, of the destination string buffer.
protocollen	[size_t*] Receives the selected protocol length excluding the null terminator.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_is_connected()

QSC_EXPORT_API bool qsc_tls_socket_is_connected

(

const qsc_tls_socket_connection *

connection

)

Test whether a TLS socket connection owns a connected socket.

Parameters

connection

[const struct*] A pointer to the TLS socket connection.

Returns

[bool] Returns true when the connection is socket-connected.

qsc_tls_socket_is_handshake_complete()

QSC_EXPORT_API bool qsc_tls_socket_is_handshake_complete

(

const qsc_tls_socket_connection *

connection

)

Test whether the TLS handshake has completed.

Parameters

connection

[const struct*] A pointer to the TLS socket connection.

Returns

[bool] Returns true when the TLS handshake has completed.

qsc_tls_socket_key_update()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_key_update	(	qsc_tls_socket_connection *	connection,
		bool	requestpeerupdate )

Request a TLS 1.3 KeyUpdate operation on a completed connection.

Parameters

connection	[struct*] A pointer to the established TLS socket connection.
requestpeerupdate	[bool] Request that the peer also update its sending keys when true.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_listener_accept()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_listener_accept	(	qsc_tls_socket_listener *	listener,
		qsc_tls_socket_connection *	connection )

Accept an inbound socket and complete a TLS server handshake.

Parameters

listener	[struct*] A pointer to the bound and listening TLS listener.
connection	[struct*] A pointer to the connection structure to receive the accepted connection.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_listener_bind()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_listener_bind	(	qsc_tls_socket_listener *	listener,
		const qsc_tls_socket_context *	context,
		const char *	address,
		uint16_t	port,
		qsc_socket_address_families	family )

Bind a TLS listener to a local address and port.

Parameters

listener	[struct*] A pointer to the initialized listener.
context	[const struct*] A pointer to the initialized server context.
address	[const char*] The null-terminated local address string.
port	[uint16_t] The local TCP port.
family	[enum] The socket address family.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_listener_close()

QSC_EXPORT_API void qsc_tls_socket_listener_close

(

qsc_tls_socket_listener *

listener

)

Close a TLS socket listener.

Parameters

listener

[struct*] A pointer to the listener to close.

qsc_tls_socket_listener_initialize()

QSC_EXPORT_API void qsc_tls_socket_listener_initialize

(

qsc_tls_socket_listener *

listener

)

Initialize a TLS socket listener structure.

Parameters

listener

[struct*] A pointer to the listener structure to initialize.

qsc_tls_socket_listener_set_options()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_listener_set_options	(	qsc_tls_socket_listener *	listener,
		bool	reuseaddress,
		bool	nodelay,
		uint32_t	recvtimeoutms,
		uint32_t	sendtimeoutms )

Set basic listener socket options.

Parameters

listener	[struct*] A pointer to the initialized listener.
reuseaddress	[bool] Enable address reuse when true.
nodelay	[bool] Enable TCP no-delay when true.
recvtimeoutms	[uint32_t] The receive timeout in milliseconds.
sendtimeoutms	[uint32_t] The send timeout in milliseconds.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_listener_set_socket_options()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_listener_set_socket_options	(	qsc_tls_socket_listener *	listener,
		const qsc_tls_socket_options *	options )

Set the full listener socket option structure.

Parameters

listener	[struct*] A pointer to the initialized listener.
options	[const struct*] A pointer to the socket options to copy into the listener.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_negotiated_cipher_suite()

QSC_EXPORT_API qsc_tls_cipher_suite qsc_tls_socket_negotiated_cipher_suite

(

const qsc_tls_socket_connection *

connection

)

Get the negotiated TLS cipher suite.

Parameters

connection

[const struct*] A pointer to the TLS socket connection.

Returns

[qsc_tls_cipher_suite] Returns the negotiated cipher suite, or the lower-layer default value when unavailable.

qsc_tls_socket_negotiated_group()

QSC_EXPORT_API qsc_tls_named_group qsc_tls_socket_negotiated_group

(

const qsc_tls_socket_connection *

connection

)

Get the negotiated TLS named group.

Parameters

connection

[const struct*] A pointer to the TLS socket connection.

Returns

[qsc_tls_named_group] Returns the negotiated named group, or the lower-layer default value when unavailable.

qsc_tls_socket_negotiated_signature_scheme()

QSC_EXPORT_API qsc_tls_signature_scheme qsc_tls_socket_negotiated_signature_scheme

(

const qsc_tls_socket_connection *

connection

)

Get the negotiated TLS signature scheme.

Parameters

connection

[const struct*] A pointer to the TLS socket connection.

Returns

[qsc_tls_signature_scheme] Returns the negotiated signature scheme, or the lower-layer default value when unavailable.

qsc_tls_socket_options_initialize_default()

QSC_EXPORT_API void qsc_tls_socket_options_initialize_default

(

qsc_tls_socket_options *

options

)

Initialize socket options to the wrapper default values.

Parameters

options

[struct*] A pointer to the socket options structure to initialize.

qsc_tls_socket_receive()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_receive	(	qsc_tls_socket_connection *	connection,
		uint8_t *	output,
		size_t	outlen,
		size_t *	read )

Receive application data from a completed TLS socket connection.

Parameters

connection	[struct*] A pointer to the established TLS socket connection.
output	[uint8_t*] A pointer to the plaintext output buffer.
outlen	[size_t] The output buffer length in bytes.
read	[size_t*] Receives the number of plaintext bytes written to output.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_receive_frame()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_receive_frame	(	qsc_tls_socket_connection *	connection,
		uint8_t *	output,
		size_t	outlen,
		size_t *	read )

Receive a length-prefixed framed application message.

The frame format is a four-byte big-endian unsigned payload length followed by the payload bytes. If the encoded frame length exceeds the output capacity, the call returns an error. Zero-length frames are accepted and set read to zero.

Parameters

connection	[struct*] A pointer to the established TLS socket connection.
output	[uint8_t*] A pointer to the application payload output buffer. This parameter may be NULL only when outlen is zero.
outlen	[size_t] The output buffer length in bytes.
read	[size_t*] Receives the number of payload bytes written to output.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_result_clear()

QSC_EXPORT_API void qsc_tls_socket_result_clear

(

qsc_tls_socket_result *

result

)

Clear a TLS socket structured result.

Parameters

result

[struct*] A pointer to the result structure to clear.

qsc_tls_socket_send()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_send	(	qsc_tls_socket_connection *	connection,
		const uint8_t *	input,
		size_t	inlen,
		size_t *	written )

Send application data over a completed TLS socket connection.

Parameters

connection	[struct*] A pointer to the established TLS socket connection.
input	[const uint8_t*] A pointer to the plaintext application data to send.
inlen	[size_t] The input length in bytes.
written	[size_t*] Receives the number of plaintext bytes accepted for transmission, or NULL.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_send_frame()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_send_frame	(	qsc_tls_socket_connection *	connection,
		const uint8_t *	input,
		size_t	inlen )

Send a length-prefixed framed application message.

The frame format is a four-byte big-endian unsigned payload length followed by the payload bytes. The payload length must not exceed QSC_TLS_SOCKET_FRAME_SIZE_MAX. Zero-length frames are permitted and encode only the four-byte length header.

Parameters

connection	[struct*] A pointer to the established TLS socket connection.
input	[const uint8_t*] A pointer to the application payload. This parameter may be NULL only when inlen is zero.
inlen	[size_t] The payload length in bytes.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_server_configure()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_configure	(	qsc_tls_socket_server *	server,
		const qsc_tls_socket_context *	context,
		const char *	address,
		uint16_t	port,
		qsc_socket_address_families	family )

Configure a TLS socket server listener and context.

Parameters

server	[struct*] A pointer to the initialized server.
context	[const struct*] A pointer to the initialized server context.
address	[const char*] The null-terminated local address string.
port	[uint16_t] The local TCP port.
family	[enum] The socket address family.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_server_dispose()

QSC_EXPORT_API void qsc_tls_socket_server_dispose

(

qsc_tls_socket_server *

server

)

Dispose of a TLS socket server and clear owned connection state.

Parameters

server

[struct*] A pointer to the server to dispose.

qsc_tls_socket_server_initialize()

QSC_EXPORT_API void qsc_tls_socket_server_initialize

(

qsc_tls_socket_server *

server

)

Initialize a TLS socket server structure.

Parameters

server

[struct*] A pointer to the server structure to initialize.

qsc_tls_socket_server_send_session_ticket()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_send_session_ticket	(	qsc_tls_socket_connection *	connection,
		uint32_t	lifetime_seconds,
		qsc_tls_session_ticket *	ticketout )

Send a TLS server session ticket over a completed server connection.

Parameters

connection	[struct*] A pointer to the established server-side TLS socket connection.
lifetime_seconds	[uint32_t] The ticket lifetime hint in seconds.
ticketout	[struct*] Receives a copy of the emitted ticket, or NULL.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_server_set_callbacks()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_set_callbacks	(	qsc_tls_socket_server *	server,
		qsc_tls_socket_server_connect_callback	onconnect,
		qsc_tls_socket_server_receive_callback	onreceive,
		qsc_tls_socket_server_disconnect_callback	ondisconnect,
		qsc_tls_socket_server_error_callback	onerror,
		void *	state )

Set the application callbacks for a TLS socket server.

Parameters

server	[struct*] A pointer to the initialized server.
onconnect	[function] The callback invoked after a successful TLS handshake, or NULL.
onreceive	[function] The callback invoked when application data is received, or NULL.
ondisconnect	[function] The callback invoked when a connection is closed, or NULL.
onerror	[function] The callback invoked when an error occurs, or NULL.
state	[void*] The user-defined callback state pointer.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_server_set_log_callback()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_set_log_callback	(	qsc_tls_socket_server *	server,
		qsc_tls_socket_log_callback	callback,
		void *	state )

Set the server-level structured logging callback.

Parameters

server	[struct*] A pointer to the initialized server.
callback	[function] The logging callback pointer, or NULL to disable server logging.
state	[void*] The user-defined callback state pointer.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_server_set_max_clients()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_set_max_clients	(	qsc_tls_socket_server *	server,
		size_t	maxclients )

Set the maximum number of concurrent client connections accepted by the server.

Parameters

server	[struct*] A pointer to the initialized server.
maxclients	[size_t] The maximum number of clients. The value must not exceed QSC_TLS_SOCKET_SERVER_CONNECTIONS_MAX.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_server_start()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_start

(

qsc_tls_socket_server *

server

)

Start the server in blocking sequential mode.

Sequential mode accepts one TLS connection at a time and processes received application data through the configured callbacks until the connection closes or the server is stopped.

Parameters

server

[struct*] A pointer to the configured server.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on normal completion.

qsc_tls_socket_server_start_concurrent()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_server_start_concurrent

(

qsc_tls_socket_server *

server

)

Start the server in bounded concurrent mode.

Concurrent mode accepts inbound TLS connections into a fixed pool of connection slots and dispatches one worker per accepted connection, up to the configured maximum client count.

Parameters

server

[struct*] A pointer to the configured server.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on normal completion.

qsc_tls_socket_server_stop()

QSC_EXPORT_API void qsc_tls_socket_server_stop

(

qsc_tls_socket_server *

server

)

Stop a running TLS socket server.

The stop operation clears the running flag, closes the listener, requests cancellation of active connection slots, and allows worker cleanup to complete through the fixed connection pool.

Parameters

server

[struct*] A pointer to the running server.

qsc_tls_socket_session_ticket_is_valid()

QSC_EXPORT_API bool qsc_tls_socket_session_ticket_is_valid

(

const qsc_tls_session_ticket *

ticket

)

Test whether a session ticket is structurally acceptable for resumption.

Parameters

ticket

[const struct*] A pointer to the session ticket to validate.

Returns

[bool] Returns true when the ticket fields are structurally valid.

qsc_tls_socket_shutdown()

QSC_EXPORT_API qsc_tls_socket_status qsc_tls_socket_shutdown

(

qsc_tls_socket_connection *

connection

)

Send a TLS close_notify alert and close the TLS socket connection.

Parameters

connection

[struct*] A pointer to the established TLS socket connection.

Returns

[qsc_tls_socket_status] Returns qsc_tls_socket_status_success on success.

qsc_tls_socket_status_string()

QSC_EXPORT_API const char * qsc_tls_socket_status_string

(

qsc_tls_socket_status

status

)

Return a constant string for a TLS socket wrapper status value.

Parameters

status

[enum] The TLS socket wrapper status value.

Returns

[const char*] Returns a constant null-terminated status string.

qsc_tls_socket_ticket_policy_initialize_default()

QSC_EXPORT_API void qsc_tls_socket_ticket_policy_initialize_default

(

qsc_tls_socket_ticket_policy *

policy

)

Initialize a session ticket policy to the wrapper default values.

Parameters

policy

[struct*] A pointer to the ticket policy structure to initialize.