tls.h File Reference

RTSPS (RTSP over TLS) support. More...

#include <compy/writer.h>
#include <stddef.h>
#include <unistd.h>
#include <compy/priv/compiler_attrs.h>

Include dependency graph for tls.h:

Go to the source code of this file.

Data Structures
struct	Compy_TlsConfig
	TLS configuration. More...

Typedefs
typedef struct Compy_TlsContext	Compy_TlsContext
	Opaque TLS context (holds loaded cert/key, shared across connections).
typedef struct Compy_TlsConn	Compy_TlsConn
	Opaque per-connection TLS state.

Enumerations
enum	Compy_TlsCipherPreference { COMPY_TLS_CIPHER_DEFAULT = 0 , COMPY_TLS_CIPHER_CHACHA20_ONLY }
	TLS ciphersuite preference presets. More...

Functions
Compy_TlsContext *	Compy_TlsContext_new (Compy_TlsConfig config) COMPY_PRIV_MUST_USE
	Creates a new TLS context from configuration.
void	Compy_TlsContext_free (Compy_TlsContext *ctx)
	Frees a TLS context.
int	Compy_TlsContext_set_cipher_preference (Compy_TlsContext *ctx, Compy_TlsCipherPreference pref)
	Sets the ciphersuite preference for all connections accepted through this context.
Compy_TlsConn *	Compy_TlsConn_accept (Compy_TlsContext *ctx, int fd) COMPY_PRIV_MUST_USE
	Performs server-side TLS handshake on fd.
Compy_Writer	compy_tls_writer (Compy_TlsConn *conn) COMPY_PRIV_MUST_USE
	Creates a Compy_Writer backed by a TLS connection.
ssize_t	compy_tls_read (Compy_TlsConn *conn, void *buf, size_t len) COMPY_PRIV_MUST_USE
	Reads decrypted data from a TLS connection.
int	compy_tls_shutdown (Compy_TlsConn *conn)
	Shuts down the TLS connection gracefully.
void	Compy_TlsConn_free (Compy_TlsConn *conn)
	Frees per-connection TLS state.

Detailed Description

RTSPS (RTSP over TLS) support.

Provides server-side TLS for encrypted RTSP signaling. The application creates a TLS context (loading cert/key), accepts TLS connections, and uses the TLS writer for encrypted I/O. The TLS reader decrypts incoming RTSP requests.

Requires a compiled TLS backend (wolfSSL, mbedTLS, OpenSSL, or BearSSL).

Enumeration Type Documentation

Compy_TlsCipherPreference

enum Compy_TlsCipherPreference

TLS ciphersuite preference presets.

Selected via Compy_TlsContext_set_cipher_preference(). These let the application steer the server toward a particular cipher family when the choice has meaningful performance or compliance implications on the target platform. The actual TLS cipher suite enums are managed inside compy; applications only pick the preset.

Enumerator
COMPY_TLS_CIPHER_DEFAULT	Backend defaults (typically GCM-first in TLS 1.3).
COMPY_TLS_CIPHER_CHACHA20_ONLY	TLS 1.3: allow only CHACHA20-POLY1305-SHA256. Clients that offer it will select it; clients that don't fall back to TLS 1.2. TLS 1.2: prefer AES-CBC-SHA256 → CCM → GCM (order chosen for servers where AES runs through a hardware engine like /dev/aes but there is no HW GHASH, so the CBC/CCM path has less per-record overhead than GCM). Motivation: on Ingenic T-series and similar slow MIPS SoCs each AES-GCM TLS record pays an ioctl + DMA setup + 4-bit-table GHASH. Scalar ChaCha20-Poly1305 in userspace wins at typical RTSP-over- TLS bitrates (~1-5 Mbps) because it has no per-record fixed cost.

Function Documentation

compy_tls_read()

ssize_t compy_tls_read	(	Compy_TlsConn *	conn,
		void *	buf,
		size_t	len
	)

Reads decrypted data from a TLS connection.

Used by the event-loop integration to read RTSP requests arriving over an encrypted connection.

Parameters

[in]	conn	The TLS connection.
[out]	buf	Buffer to read into.
[in]	len	Maximum bytes to read.

Precondition

conn != NULL

buf != NULL

Returns

Bytes read, 0 on EOF, -1 on error.

compy_tls_shutdown()

int compy_tls_shutdown

(

Compy_TlsConn *

conn

)

Shuts down the TLS connection gracefully.

Returns

0 on success, -1 on error.

compy_tls_writer()

Compy_Writer compy_tls_writer

(

Compy_TlsConn *

conn

)

Creates a Compy_Writer backed by a TLS connection.

All data written through this writer is encrypted via TLS before being sent on the underlying socket.

Parameters

[in]

conn

The TLS connection.

Precondition

conn != NULL

Compy_TlsConn_accept()

Compy_TlsConn * Compy_TlsConn_accept	(	Compy_TlsContext *	ctx,
		int	fd
	)

Performs server-side TLS handshake on fd.

This is a blocking call that completes the full TLS handshake.

Parameters

[in]	ctx	The TLS context with loaded cert/key.
[in]	fd	The connected socket file descriptor.

Precondition

ctx != NULL

fd >= 0

Returns

A new TLS connection, or NULL on handshake failure.

Compy_TlsContext_new()

Compy_TlsContext * Compy_TlsContext_new

(

Compy_TlsConfig

config

)

Creates a new TLS context from configuration.

Parameters

[in]

config

Certificate and key file paths.

Precondition

config.cert_path != NULL

config.key_path != NULL

Returns

A new TLS context, or NULL on failure (cert/key load error).

Compy_TlsContext_set_cipher_preference()

int Compy_TlsContext_set_cipher_preference	(	Compy_TlsContext *	ctx,
		Compy_TlsCipherPreference	pref
	)

Sets the ciphersuite preference for all connections accepted through this context.

Must be called before the first Compy_TlsConn_accept().

Parameters

[in]	ctx	TLS context.
[in]	pref	Preset to apply.

Returns

0 on success; -1 if the backend does not support ciphersuite preference, or if pref is not a recognized preset.

Precondition

ctx != NULL