tlsio.h File Reference

Blocking socket adapter around qsc_tls_connection. More...

#include "qsccommon.h"
#include "tlserrors.h"
#include "tlsengine.h"
#include "socket.h"

Go to the source code of this file.

Data Structures
struct	qsc_tls_io_connection
	Stores the non-owning association between a TLS engine and a socket. More...

Macros
#define	QSC_TLS_IO_RECV_CHUNK   4096U
	Maximum number of socket bytes requested by one blocking receive call.
#define	QSC_TLS_IO_RX_BUFFER_SIZE   QSC_TLS_STREAM_BUFFER_MAX_SIZE
	Persistent inbound TLS stream buffer size used by the socket adapter.

Typedefs
typedef struct qsc_tls_io_connection	qsc_tls_io_connection

Functions
QSC_EXPORT_API qsc_tls_status	qsc_tls_io_attach (qsc_tls_io_connection *io, qsc_tls_connection *engine, qsc_socket *socket)
	Attach a TLS engine and socket to an I/O adapter.
QSC_EXPORT_API qsc_tls_status	qsc_tls_io_handshake (qsc_tls_io_connection *io)
	Drive the TLS handshake to completion over the attached blocking socket.
QSC_EXPORT_API qsc_tls_status	qsc_tls_io_send (qsc_tls_io_connection *io, const uint8_t *input, size_t inlen, size_t *written)
	Encrypt and send application data over the attached socket.
QSC_EXPORT_API qsc_tls_status	qsc_tls_io_receive (qsc_tls_io_connection *io, uint8_t *output, size_t outlen, size_t *read)
	Receive and decrypt application data from the attached socket.
QSC_EXPORT_API qsc_tls_status	qsc_tls_io_shutdown (qsc_tls_io_connection *io)
	Emit and send a close_notify alert for the attached connection.

Detailed Description

Blocking socket adapter around qsc_tls_connection.

This header provides a transport adapter that binds a qsc_tls_connection to a qsc_socket and drives the TLS engine using blocking send and receive calls. The adapter does not allocate or own the engine or the socket. It only stores non-owning pointers and marshals bytes between the engine record interface and the socket API.

The adapter maintains a persistent inbound stream buffer. TCP is a byte-stream transport and does not preserve TLS record boundaries. A single socket receive can return a partial record, exactly one record, or multiple coalesced records. The persistent buffer preserves any unconsumed bytes between handshake, application receive, post-handshake, and shutdown processing.

Function Documentation

qsc_tls_io_attach()

QSC_EXPORT_API qsc_tls_status qsc_tls_io_attach	(	qsc_tls_io_connection *	io,
		qsc_tls_connection *	engine,
		qsc_socket *	socket )

Attach a TLS engine and socket to an I/O adapter.

Parameters

io	[struct*] The I/O adapter to initialize.
engine	[struct*] The TLS engine to attach.
socket	[struct*] The blocking socket to attach.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.

qsc_tls_io_handshake()

QSC_EXPORT_API qsc_tls_status qsc_tls_io_handshake

(

qsc_tls_io_connection *

io

)

Drive the TLS handshake to completion over the attached blocking socket.

Repeatedly calls the TLS engine handshake function, flushing any produced outbound flight to the socket and receiving additional input whenever the engine requires more record bytes. The call returns when the handshake completes or a fatal error occurs. Any unconsumed bytes received during the handshake remain in the persistent stream buffer for later application or post-handshake processing.

Parameters

io	[struct*] The attached I/O adapter.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.

qsc_tls_io_receive()

QSC_EXPORT_API qsc_tls_status qsc_tls_io_receive	(	qsc_tls_io_connection *	io,
		uint8_t *	output,
		size_t	outlen,
		size_t *	read )

Receive and decrypt application data from the attached socket.

Receives socket bytes until at least one complete TLS record has been assembled and consumed. If the socket read also contains bytes from later TLS records, those bytes are preserved in the persistent stream buffer for the next call.

Parameters

io	[struct*] The attached I/O adapter.
output	[uint8_t*] The destination buffer for decrypted application data.
outlen	[size_t] The destination buffer length in bytes.
read	[size_t*] Receives the number of plaintext bytes written to output.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.

qsc_tls_io_send()

QSC_EXPORT_API qsc_tls_status qsc_tls_io_send	(	qsc_tls_io_connection *	io,
		const uint8_t *	input,
		size_t	inlen,
		size_t *	written )

Encrypt and send application data over the attached socket.

Parameters

io	[struct*] The attached I/O adapter.
input	[const uint8_t*] The plaintext application data.
inlen	[size_t] The plaintext length in bytes.
written	[size_t*] Receives the number of plaintext bytes accepted for transmission.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.

qsc_tls_io_shutdown()

QSC_EXPORT_API qsc_tls_status qsc_tls_io_shutdown

(

qsc_tls_io_connection *

io

)

Emit and send a close_notify alert for the attached connection.

Parameters

io	[struct*] The attached I/O adapter.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.