File syn_tls.h¶

Native Zero-Heap TLS 1.3 Protocol Engine & Transport Adapter (RFC 8446). More...

#include "syntropic/crypto/syn_aes.h"
#include "syntropic/crypto/syn_chacha20poly1305.h"
#include "syntropic/crypto/syn_hkdf.h"
#include "syntropic/crypto/syn_sha256.h"
#include "syntropic/crypto/syn_x25519.h"
#include "syntropic/crypto/syn_x509.h"
#include "syntropic/net/syn_transport.h"
#include "syntropic/pt/syn_pt.h"
#include "syntropic/sched/syn_task.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_TLS_Config
struct	SYN_TLS_Context

Public Types¶

Type	Name
enum	SYN_TLS_AuthMode
enum	SYN_TLS_CipherSuite
enum	SYN_TLS_State

Public Functions¶

Type	Name
void	syn_tls_bind_transport (SYN_TLS_Context * tls_ctx, SYN_Transport * tr_out) Wrap a TLS 1.3 context into a standard SYN_Transport abstraction.
bool	syn_tls_handshake (SYN_TLS_Context * ctx) Perform a non-blocking TLS 1.3 handshake step.
bool	syn_tls_init (SYN_TLS_Context * ctx, const SYN_TLS_Config * config, SYN_Transport * transport, uint8_t * rx_buf, size_t rx_buf_size, uint8_t * tx_buf, size_t tx_buf_size) Initialize a TLS 1.3 context.
bool	syn_tls_recv (SYN_TLS_Context * ctx, uint8_t * data, size_t max_len, size_t * out_len) Receive and decrypt TLS 1.3 record payload into caller buffer.
bool	syn_tls_send (SYN_TLS_Context * ctx, const uint8_t * data, size_t len) Encrypt and transmit application data payload over TLS 1.3.
SYN_PT_Status	syn_tls_task (SYN_PT * pt, SYN_Task * task) Cooperative protothread task — drives the TLS 1.3 client handshake & session.

Public Static Functions¶

Type	Name
SYN_TLS_State	syn_tls_get_state (const SYN_TLS_Context * ctx) Retrieve current TLS 1.3 state machine state.
bool	syn_tls_is_established (const SYN_TLS_Context * ctx) Check if the TLS 1.3 session is established and ready for app data.

Macros¶

Type	Name
define	SYN_TLS_RECORD_MAX_PAYLOAD `2048U` Maximum TLS record payload size in bytes (2048).
define	SYN_TLS_SECRET_LEN `48U` Length of TLS 1.3 secret keys in bytes (48 for SHA-384 / SHA-256 capacity).

Detailed Description¶

Implements TLS 1.3 Client & Server handshakes and encrypted record layer. Supported modes: * Pre-Shared Key (PSK / PSK-DHE) * Raw Public Key (RPK) - RFC 7250 * X.509 Server Authentication & Mutual TLS (mTLS)

Plugs into standard SYN_Transport interface.

Public Types Documentation¶

enum SYN_TLS_AuthMode¶

enum SYN_TLS_AuthMode {
    SYN_TLS_AUTH_MODE_PSK = 0,
    SYN_TLS_AUTH_MODE_RAW_PUBKEY,
    SYN_TLS_AUTH_MODE_X509_SERVER,
    SYN_TLS_AUTH_MODE_MTLS
};

TLS 1.3 Authentication Mode

enum SYN_TLS_CipherSuite¶

enum SYN_TLS_CipherSuite {
    SYN_TLS_CIPHER_SUITE_CHACHA20_POLY1305_SHA256 = 0,
    SYN_TLS_CIPHER_SUITE_AES_128_GCM_SHA256 = 1,
    SYN_TLS_CIPHER_SUITE_AES_256_GCM_SHA384 = 2,
    SYN_TLS_CIPHER_SUITE_AES_128_CCM_SHA256 = 3,
    SYN_TLS_CIPHER_SUITE_AES_128_CCM_8_SHA256 = 4
};

TLS 1.3 Cipher Suite

enum SYN_TLS_State¶

enum SYN_TLS_State {
    SYN_TLS_STATE_UNINITIALIZED = 0,
    SYN_TLS_STATE_CLIENT_HELLO_SENT,
    SYN_TLS_STATE_SERVER_HELLO_RECEIVED,
    SYN_TLS_STATE_HANDSHAKE_KEYS_DERIVED,
    SYN_TLS_STATE_CERTIFICATE_VERIFIED,
    SYN_TLS_STATE_FINISHED_SENT,
    SYN_TLS_STATE_ESTABLISHED,
    SYN_TLS_STATE_ERROR
};

TLS 1.3 Handshake State Machine States

Public Functions Documentation¶

function syn_tls_bind_transport¶

Wrap a TLS 1.3 context into a standard SYN_Transport abstraction.

void syn_tls_bind_transport (
    SYN_TLS_Context * tls_ctx,
    SYN_Transport * tr_out
)

Parameters:

tls_ctx Initialized TLS 1.3 context.
tr_out [out] Output transport instance.

function syn_tls_handshake¶

Perform a non-blocking TLS 1.3 handshake step.

bool syn_tls_handshake (
    SYN_TLS_Context * ctx
)

Parameters:

ctx TLS 1.3 context.

Returns:

true if handshake completed or progressing, false on fatal error.

function syn_tls_init¶

Initialize a TLS 1.3 context.

bool syn_tls_init (
    SYN_TLS_Context * ctx,
    const SYN_TLS_Config * config,
    SYN_Transport * transport,
    uint8_t * rx_buf,
    size_t rx_buf_size,
    uint8_t * tx_buf,
    size_t tx_buf_size
)

Parameters:

ctx Context to initialize.
config Configuration.
transport Wire transport instance.
rx_buf Caller-owned RX record buffer.
rx_buf_size RX buffer capacity.
tx_buf Caller-owned TX record buffer.
tx_buf_size TX buffer capacity.

Returns:

true on success.

function syn_tls_recv¶

Receive and decrypt TLS 1.3 record payload into caller buffer.

bool syn_tls_recv (
    SYN_TLS_Context * ctx,
    uint8_t * data,
    size_t max_len,
    size_t * out_len
)

Parameters:

ctx TLS 1.3 context.
data [out] Output buffer for decrypted data.
max_len Capacity of output buffer.
out_len [out] Actual decrypted bytes written.

Returns:

true if a complete record decrypted.

function syn_tls_send¶

Encrypt and transmit application data payload over TLS 1.3.

bool syn_tls_send (
    SYN_TLS_Context * ctx,
    const uint8_t * data,
    size_t len
)

Parameters:

ctx TLS 1.3 context.
data Application data buffer.
len Application data length.

Returns:

true if record encrypted and sent successfully.

function syn_tls_task¶

Cooperative protothread task — drives the TLS 1.3 client handshake & session.

SYN_PT_Status syn_tls_task (
    SYN_PT * pt,
    SYN_Task * task
)

Parameters:

pt Protothread handle.
task Task descriptor.

Returns:

PT status.

Public Static Functions Documentation¶

function syn_tls_get_state¶

Retrieve current TLS 1.3 state machine state.

static inline SYN_TLS_State syn_tls_get_state (
    const SYN_TLS_Context * ctx
)

Parameters:

ctx TLS 1.3 context.

Returns:

Current SYN_TLS_State.

function syn_tls_is_established¶

Check if the TLS 1.3 session is established and ready for app data.

static inline bool syn_tls_is_established (
    const SYN_TLS_Context * ctx
)

Parameters:

ctx TLS 1.3 context.

Returns:

true if established.

Macro Definition Documentation¶

define SYN_TLS_RECORD_MAX_PAYLOAD¶

Maximum TLS record payload size in bytes (2048).

#define SYN_TLS_RECORD_MAX_PAYLOAD `2048U`

define SYN_TLS_SECRET_LEN¶

Length of TLS 1.3 secret keys in bytes (48 for SHA-384 / SHA-256 capacity).

#define SYN_TLS_SECRET_LEN `48U`

The documentation for this class was generated from the following file src/syntropic/net/syn_tls.h