Secure Sockets Layer (SSL/TLS)

Components for secure, encrypted TCP communication (requires OpenSSL). More...

Collaboration diagram for Secure Sockets Layer (SSL/TLS):

Files
file	listener.h
	Implementation of a secure SSL/TLS listener for the QB IO library.
file	socket.h
	Implementation of SSL/TLS sockets for secure TCP communication in the QB IO library.
file	saccept.h
	Secure (SSL/TLS) TCP connection acceptance transport for the QB IO library.
file	stcp.h
	Secure TCP (SSL/TLS) stream transport for the QB IO library.

Classes
class	qb::io::tcp::ssl::listener
	Class implementing a secure SSL/TLS TCP listener for accepting encrypted connections. More...
struct	qb::io::ssl::Certificate
	Structure to hold essential SSL certificate information. More...
struct	qb::io::ssl::Session
	Opaque wrapper for an OpenSSL SSL_SESSION object. More...
class	qb::io::tcp::ssl::socket
	Class implementing secure SSL/TLS TCP socket functionality. More...

Functions
Certificate	qb::io::ssl::get_certificate (SSL *ssl)
	Extract certificate information from an active SSL connection.
SSL_CTX *	qb::io::ssl::create_client_context (const SSL_METHOD *method)
	Create an SSL context (SSL_CTX) configured for client-side SSL/TLS operations.
SSL_CTX *	qb::io::ssl::create_server_context (const SSL_METHOD *method, std::filesystem::path cert_path, std::filesystem::path key_path)
	Create an SSL context (SSL_CTX) configured for server-side SSL/TLS operations.
bool	qb::io::ssl::load_ca_certificates (SSL_CTX *ctx, const std::string &ca_file_path)
	Load CA certificates from a file for peer verification.
bool	qb::io::ssl::load_ca_directory (SSL_CTX *ctx, const std::string &ca_dir_path)
	Load CA certificates from a directory for peer verification.
bool	qb::io::ssl::set_cipher_list (SSL_CTX *ctx, const std::string &ciphers)
	Set the preferred cipher suites for TLS 1.2 and earlier.
bool	qb::io::ssl::set_ciphersuites_tls13 (SSL_CTX *ctx, const std::string &ciphersuites)
	Set the preferred cipher suites for TLS 1.3.
bool	qb::io::ssl::set_tls_protocol_versions (SSL_CTX *ctx, int min_version, int max_version)
	Set the minimum and maximum TLS protocol versions.
bool	qb::io::ssl::configure_mtls_server_context (SSL_CTX *ctx, const std::string &client_ca_file_path, int verification_mode=SSL_VERIFY_PEER)
	Configure client certificate authentication (mTLS) for a server SSL_CTX.
bool	qb::io::ssl::configure_client_certificate (SSL_CTX *ctx, const std::string &client_cert_path, const std::string &client_key_path)
	Configure a client SSL_CTX to use a specific client certificate and private key.
bool	qb::io::ssl::set_alpn_protos_client (SSL_CTX *ctx, const std::vector< std::string > &protocols)
	Set the ALPN protocols for a client SSL_CTX to offer during handshake.
bool	qb::io::ssl::set_alpn_selection_callback_server (SSL_CTX *ctx, SSL_CTX_alpn_select_cb_func callback, void *arg)
	Set the ALPN selection callback for a server SSL_CTX.
bool	qb::io::ssl::enable_server_session_caching (SSL_CTX *ctx, long cache_size)
	Enable and configure server-side SSL session caching.
bool	qb::io::ssl::disable_client_session_cache (SSL_CTX *ctx)
	Disable client-side SSL session caching for an SSL_CTX.
bool	qb::io::ssl::set_custom_verify_callback (SSL_CTX *ctx, int(*callback)(int, X509_STORE_CTX *), int verification_mode)
	Set a custom callback for X.509 certificate verification.
bool	qb::io::ssl::set_ocsp_stapling_client_callback (SSL_CTX *ctx, int(*callback)(SSL *s, void *arg), void *arg)
	Set a callback for the client to handle stapled OCSP responses from the server.
bool	qb::io::ssl::set_ocsp_stapling_responder_server (SSL_CTX *ctx, int(*callback)(SSL *s, void *arg), void *arg)
	Set a callback for the server to provide an OCSP response to be stapled.
bool	qb::io::ssl::set_sni_hostname_selection_callback_server (SSL_CTX *ctx, int(*callback)(SSL *s, int *al, void *arg), void *arg)
	Set a callback for server-side SNI (Server Name Indication) handling.
bool	qb::io::ssl::set_keylog_callback (SSL_CTX *ctx, SSL_CTX_keylog_cb_func callback)
	Set the SSL/TLS key log callback function.
bool	qb::io::ssl::configure_dh_parameters_server (SSL_CTX *ctx, const std::string &dh_param_file_path)
	Configure Diffie-Hellman parameters for a server SSL_CTX.
bool	qb::io::ssl::configure_ecdh_curves_server (SSL_CTX *ctx, const std::string &curve_names_list)
	Configure preferred ECDH curves for a server SSL_CTX.
void	qb::io::ssl::free_session (Session &session)
	Frees an SSL_SESSION object held by qb::io::ssl::Session.
bool	qb::io::ssl::enable_post_handshake_auth_server (SSL_CTX *ctx)
	Enable server-side support for TLS 1.3 Post-Handshake Authentication (PHA).

Detailed Description

Components for secure, encrypted TCP communication (requires OpenSSL).

Includes `qb::io::tcp::ssl::socket` and `qb::io::tcp::ssl::listener`.

Function Documentation

get_certificate()

Certificate qb::io::ssl::get_certificate

(

SSL *

ssl

)

Extract certificate information from an active SSL connection.

Parameters

ssl	Pointer to the SSL connection structure (SSL*) from which to extract certificate details.

Returns

A qb::io::ssl::Certificate structure populated with the subject, issuer, and version of the peer's certificate. Returns an empty/default-initialized struct if no certificate is available or an error occurs.

create_client_context()

SSL_CTX * qb::io::ssl::create_client_context

(

const SSL_METHOD *

method

)

Create an SSL context (SSL_CTX) configured for client-side SSL/TLS operations.

Parameters

method

The SSL/TLS method to use (e.g., TLS_client_method(), SSLv23_client_method()).

Returns

Pointer to the newly created SSL_CTX on success, nullptr on failure.

Note

The caller is responsible for freeing the returned SSL_CTX using SSL_CTX_free().

create_server_context()

SSL_CTX * qb::io::ssl::create_server_context	(	const SSL_METHOD *	method,
		std::filesystem::path	cert_path,
		std::filesystem::path	key_path )

Create an SSL context (SSL_CTX) configured for server-side SSL/TLS operations.

Parameters

method	The SSL/TLS method to use (e.g., TLS_server_method(), SSLv23_server_method()).
cert_path	Path to the server's PEM-encoded certificate file.
key_path	Path to the server's PEM-encoded private key file.

Returns

Pointer to the newly created SSL_CTX on success, nullptr on failure (e.g., if files cannot be loaded).

Note

The caller is responsible for freeing the returned SSL_CTX using SSL_CTX_free().

load_ca_certificates()

bool qb::io::ssl::load_ca_certificates	(	SSL_CTX *	ctx,
		const std::string &	ca_file_path )

Load CA certificates from a file for peer verification.

Parameters

ctx	The SSL_CTX to configure.
ca_file_path	Path to the PEM-encoded CA certificate file.

Returns

true on success, false on failure.

load_ca_directory()

bool qb::io::ssl::load_ca_directory	(	SSL_CTX *	ctx,
		const std::string &	ca_dir_path )

Load CA certificates from a directory for peer verification.

Parameters

ctx	The SSL_CTX to configure.
ca_dir_path	Path to the directory containing PEM-encoded CA certificates. The directory must be prepared with c_rehash or equivalent.

Returns

true on success, false on failure.

set_cipher_list()

bool qb::io::ssl::set_cipher_list	(	SSL_CTX *	ctx,
		const std::string &	ciphers )

Set the preferred cipher suites for TLS 1.2 and earlier.

Parameters

ctx	The SSL_CTX to configure.
ciphers	A string in OpenSSL cipher list format (e.g., "HIGH:!aNULL:!MD5").

Returns

true on success, false on failure.

set_ciphersuites_tls13()

bool qb::io::ssl::set_ciphersuites_tls13	(	SSL_CTX *	ctx,
		const std::string &	ciphersuites )

Set the preferred cipher suites for TLS 1.3.

Parameters

ctx	The SSL_CTX to configure.
ciphersuites	A string in OpenSSL TLS 1.3 ciphersuite format (e.g., "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256").

Returns

true on success, false on failure.

set_tls_protocol_versions()

bool qb::io::ssl::set_tls_protocol_versions	(	SSL_CTX *	ctx,
		int	min_version,
		int	max_version )

Set the minimum and maximum TLS protocol versions.

Parameters

ctx	The SSL_CTX to configure.
min_version	The minimum protocol version (e.g., TLS1_2_VERSION). Use 0 for default.
max_version	The maximum protocol version (e.g., TLS1_3_VERSION). Use 0 for default.

Returns

true on success, false on failure to set either version if specified.

configure_mtls_server_context()

bool qb::io::ssl::configure_mtls_server_context	(	SSL_CTX *	ctx,
		const std::string &	client_ca_file_path,
		int	verification_mode = SSL_VERIFY_PEER )

Configure client certificate authentication (mTLS) for a server SSL_CTX.

Parameters

ctx	The server SSL_CTX to configure.
client_ca_file_path	Path to the PEM-encoded CA certificate file for verifying client certificates. If empty, system default CAs might be used, or no specific client CA is set.
verification_mode	The verification mode (e.g., SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT). Defaults to SSL_VERIFY_PEER.

Returns

true on success, false on failure.

configure_client_certificate()

bool qb::io::ssl::configure_client_certificate	(	SSL_CTX *	ctx,
		const std::string &	client_cert_path,
		const std::string &	client_key_path )

Configure a client SSL_CTX to use a specific client certificate and private key.

Parameters

ctx	The client SSL_CTX to configure.
client_cert_path	Path to the PEM-encoded client certificate file.
client_key_path	Path to the PEM-encoded client private key file.

Returns

true on success, false on failure.

set_alpn_protos_client()

bool qb::io::ssl::set_alpn_protos_client	(	SSL_CTX *	ctx,
		const std::vector< std::string > &	protocols )

Set the ALPN protocols for a client SSL_CTX to offer during handshake.

Parameters

ctx	The client SSL_CTX to configure.
protocols	A vector of protocol strings (e.g., {"h2", "http/1.1"}).

Returns

true on success, false on failure.

set_alpn_selection_callback_server()

bool qb::io::ssl::set_alpn_selection_callback_server	(	SSL_CTX *	ctx,
		SSL_CTX_alpn_select_cb_func	callback,
		void *	arg )

Set the ALPN selection callback for a server SSL_CTX.

Parameters

ctx	The server SSL_CTX to configure.
callback	The OpenSSL ALPN selection callback function.
arg	User-defined argument to be passed to the callback.

Returns

true on success (callback was set), false otherwise.

Note

See OpenSSL documentation for SSL_CTX_set_alpn_select_cb for callback signature and behavior.

enable_server_session_caching()

bool qb::io::ssl::enable_server_session_caching	(	SSL_CTX *	ctx,
		long	cache_size )

Enable and configure server-side SSL session caching.

Parameters

ctx	The server SSL_CTX to configure.
cache_size	The maximum number of sessions to store in the cache. OpenSSL's default is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT. A size of 0 means unlimited (not recommended).

Returns

true if session caching was successfully configured, false otherwise.

Note

This function enables the internal OpenSSL session cache (SSL_SESS_CACHE_SERVER).

disable_client_session_cache()

bool qb::io::ssl::disable_client_session_cache

(

SSL_CTX *

ctx

)

Disable client-side SSL session caching for an SSL_CTX.

Parameters

ctx	The client SSL_CTX to configure.

Returns

true if session caching was successfully disabled, false otherwise.

Note

This prevents SSL objects created from this context from reusing sessions.

set_custom_verify_callback()

bool qb::io::ssl::set_custom_verify_callback	(	SSL_CTX *	ctx,
		int(*	callback )(int, X509_STORE_CTX *),
		int	verification_mode )

Set a custom callback for X.509 certificate verification.

Parameters

ctx	The SSL_CTX to configure.
callback	A user-defined callback function. The callback signature is int callback(int preverify_ok, X509_STORE_CTX *x509_ctx). It should return 1 for success, 0 for failure.
verification_mode	The verification mode to set (e.g., SSL_VERIFY_PEER). This is passed to SSL_CTX_set_verify along with the callback.

Returns

true if the callback and mode were set, false on error (e.g., null context).

set_ocsp_stapling_client_callback()

bool qb::io::ssl::set_ocsp_stapling_client_callback	(	SSL_CTX *	ctx,
		int(*	callback )(SSL *s, void *arg),
		void *	arg )

Set a callback for the client to handle stapled OCSP responses from the server.

Parameters

ctx	The client SSL_CTX to configure.
callback	The callback function of type int (*cb)(SSL *, void *). Inside this callback, the user can retrieve the OCSP response using SSL_get_tlsext_status_ocsp_resp().
arg	User-defined argument to be passed to the callback.

Returns

true if the callback was set, false otherwise.

set_ocsp_stapling_responder_server()

bool qb::io::ssl::set_ocsp_stapling_responder_server	(	SSL_CTX *	ctx,
		int(*	callback )(SSL *s, void *arg),
		void *	arg )

Set a callback for the server to provide an OCSP response to be stapled.

Parameters

ctx	The server SSL_CTX to configure.
callback	The callback function of type int (*cb)(SSL *, void *). This callback is responsible for setting the OCSP response using SSL_set_tlsext_status_ocsp_resp().
arg	User-defined argument to be passed to the callback.

Returns

true if the callback was set, false otherwise.

set_sni_hostname_selection_callback_server()

bool qb::io::ssl::set_sni_hostname_selection_callback_server	(	SSL_CTX *	ctx,
		int(*	callback )(SSL *s, int *al, void *arg),
		void *	arg )

Set a callback for server-side SNI (Server Name Indication) handling.

Parameters

ctx	The server SSL_CTX on which to set the callback. This context is used if the callback doesn't switch to another one.
callback	The callback function int (*cb)(SSL *s, int *al, void *arg). This callback can inspect the server name and potentially switch to a different SSL_CTX. It should return SSL_TLSEXT_ERR_OK on success.
arg	User-defined argument to be passed to the callback.

Returns

true if the callback was set, false otherwise.

set_keylog_callback()

bool qb::io::ssl::set_keylog_callback	(	SSL_CTX *	ctx,
		SSL_CTX_keylog_cb_func	callback )

Set the SSL/TLS key log callback function.

Parameters

ctx	The SSL_CTX to configure.
callback	The keylog callback function void (*cb)(const SSL *ssl, const char *line). This function will be called with lines of text representing key material.

Returns

true if the callback was set, false on error (e.g., null context).

configure_dh_parameters_server()

bool qb::io::ssl::configure_dh_parameters_server	(	SSL_CTX *	ctx,
		const std::string &	dh_param_file_path )

Configure Diffie-Hellman parameters for a server SSL_CTX.

Parameters

ctx	The server SSL_CTX to configure.
dh_param_file_path	Path to a PEM-encoded DH parameters file.

Returns

true on success, false on failure (e.g., file not found, invalid format).

Note

Important for PFS with DHE cipher suites (TLS 1.2 and earlier).

configure_ecdh_curves_server()

bool qb::io::ssl::configure_ecdh_curves_server	(	SSL_CTX *	ctx,
		const std::string &	curve_names_list )

Configure preferred ECDH curves for a server SSL_CTX.

Parameters

ctx	The server SSL_CTX to configure.
curve_names_list	A colon-separated list of curve NIDs or names (e.g., "P-256:X25519:P-384"). If empty, OpenSSL's default list may be used or auto-selection enabled if supported.

Returns

true on success, false on failure to set the curves.

Note

Important for PFS with ECDHE cipher suites. Using SSL_CTX_set_ecdh_auto(ctx, 1) is also an option for some OpenSSL versions.

free_session()

void qb::io::ssl::free_session

(

Session &

session

)

Frees an SSL_SESSION object held by qb::io::ssl::Session.

Parameters

session

The qb::io::ssl::Session object to free. The internal handle will be nullified.

enable_post_handshake_auth_server()

bool qb::io::ssl::enable_post_handshake_auth_server

(

SSL_CTX *

ctx

)

Enable server-side support for TLS 1.3 Post-Handshake Authentication (PHA).

Parameters

ctx	The server SSL_CTX to configure.

Returns

true if PHA was successfully enabled (or was already enabled), false on error.

Note

Requires OpenSSL 1.1.1 or later. The server application will also need to handle the actual authentication request, typically via an info callback or by checking SSL_get_post_handshake_auth().