File syn_dtls.h¶

Native Zero-Heap DTLS 1.3 Datagram Protocol Engine (RFC 9147). 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_sha512.h"
#include "syntropic/crypto/syn_x25519.h"
#include "syntropic/crypto/syn_x509.h"
#include "syntropic/net/syn_tls.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_DTLS_Config
struct	SYN_DTLS_Context
struct	SYN_DTLS_ReplayWindow 64-packet Sliding Window Anti-Replay Filter (RFC 9147 Section 4.5.2).

Public Types¶

Type	Name
enum	SYN_DTLS_AuthMode
enum	SYN_DTLS_CipherSuite
enum	SYN_DTLS_Epoch
enum	SYN_DTLS_State

Public Functions¶

Type	Name
void	syn_dtls_bind_transport (SYN_DTLS_Context * dtls_ctx, SYN_Transport * tr_out) Bind DTLS 1.3 engine to abstract SYN_Transport interface.
bool	syn_dtls_handshake (SYN_DTLS_Context * ctx) Execute DTLS 1.3 handshake.
bool	syn_dtls_init (SYN_DTLS_Context * ctx, const SYN_DTLS_Config * config, SYN_Transport * transport, uint8_t * rx_buf, size_t rx_buf_size, uint8_t * tx_buf, size_t tx_buf_size) Initialize DTLS 1.3 engine context with caller-allocated memory.
bool	syn_dtls_recv (SYN_DTLS_Context * ctx, uint8_t * data, size_t max_len, size_t * out_len) Receive and decrypt a DTLS 1.3 datagram record.
bool	syn_dtls_replay_check (const SYN_DTLS_ReplayWindow * win, uint64_t seq) Check whether a sequence number is acceptable by the replay window.
void	syn_dtls_replay_update (SYN_DTLS_ReplayWindow * win, uint64_t seq) Commit a validated sequence number to the replay window.
bool	syn_dtls_send (SYN_DTLS_Context * ctx, const uint8_t * data, size_t len) Send application data protected by DTLS 1.3 AEAD datagram record.
SYN_PT_Status	syn_dtls_task (SYN_PT * pt, SYN_Task * task) Non-blocking DTLS background task (Protothread).

Macros¶

Type	Name
define	SYN_DTLS_RECORD_MAX_PAYLOAD `2048U` Maximum DTLS datagram record payload size in bytes (2048).
define	SYN_DTLS_REPLAY_WINDOW_SIZE `64U` Size of anti-replay sliding window in packets (64).
define	SYN_DTLS_SECRET_LEN `48U` Length of DTLS 1.3 secret keys in bytes (48 for SHA-384 / SHA-256 capacity).
define	SYN_DTLS_UNIFIED_CID_BIT `0x10U`
define	SYN_DTLS_UNIFIED_EPOCH_MASK `0x03U`
define	SYN_DTLS_UNIFIED_FIXED_BIT `0x20U`
define	SYN_DTLS_UNIFIED_LEN_BIT `0x04U`
define	SYN_DTLS_UNIFIED_SEQ_16BIT `0x08U`

Detailed Description¶

Implements Datagram Transport Layer Security (DTLS) version 1.3: * Unified record header format (RFC 9147 Section 4) * 64-packet sliding window anti-replay protection (RFC 9147 Section 4.5.2) * Epoch-based key scheduling & AEAD record encryption/decryption * Pre-Shared Key (PSK), Raw Public Key (RPK), and X.509 modes * Full pluggability into SYN_Transport (UDP, wireless, serial, etc.)

Public Types Documentation¶

enum SYN_DTLS_AuthMode¶

enum SYN_DTLS_AuthMode {
    SYN_DTLS_AUTH_MODE_PSK = 0,
    SYN_DTLS_AUTH_MODE_RAW_PUBKEY,
    SYN_DTLS_AUTH_MODE_X509_SERVER,
    SYN_DTLS_AUTH_MODE_MTLS
};

DTLS 1.3 Authentication Mode

enum SYN_DTLS_CipherSuite¶

enum SYN_DTLS_CipherSuite {
    SYN_DTLS_CIPHER_SUITE_CHACHA20_POLY1305_SHA256 =
        0,
    SYN_DTLS_CIPHER_SUITE_AES_128_GCM_SHA256 = 1,
    SYN_DTLS_CIPHER_SUITE_AES_256_GCM_SHA384 = 2,
    SYN_DTLS_CIPHER_SUITE_AES_128_CCM_SHA256 = 3,
    SYN_DTLS_CIPHER_SUITE_AES_128_CCM_8_SHA256 = 4
};

DTLS 1.3 Cipher Suite

enum SYN_DTLS_Epoch¶

enum SYN_DTLS_Epoch {
    SYN_DTLS_EPOCH_PLAINTEXT = 0,
    SYN_DTLS_EPOCH_EARLY_DATA = 1,
    SYN_DTLS_EPOCH_HANDSHAKE = 2,
    SYN_DTLS_EPOCH_APP_DATA = 3
};

DTLS 1.3 Epochs

enum SYN_DTLS_State¶

enum SYN_DTLS_State {
    SYN_DTLS_STATE_UNINITIALIZED = 0,
    SYN_DTLS_STATE_CLIENT_HELLO_SENT,
    SYN_DTLS_STATE_SERVER_HELLO_RECEIVED,
    SYN_DTLS_STATE_HANDSHAKE_KEYS_DERIVED,
    SYN_DTLS_STATE_CERTIFICATE_VERIFIED,
    SYN_DTLS_STATE_FINISHED_SENT,
    SYN_DTLS_STATE_ESTABLISHED,
    SYN_DTLS_STATE_ERROR
};

DTLS 1.3 Handshake State

Public Functions Documentation¶

function syn_dtls_bind_transport¶

Bind DTLS 1.3 engine to abstract SYN_Transport interface.

void syn_dtls_bind_transport (
    SYN_DTLS_Context * dtls_ctx,
    SYN_Transport * tr_out
)

Parameters:

dtls_ctx Initialized DTLS context.
tr_out [out] Transport instance to populate.

function syn_dtls_handshake¶

Execute DTLS 1.3 handshake.

bool syn_dtls_handshake (
    SYN_DTLS_Context * ctx
)

Parameters:

ctx Initialized DTLS context.

Returns:

true on successful handshake completion.

function syn_dtls_init¶

Initialize DTLS 1.3 engine context with caller-allocated memory.

bool syn_dtls_init (
    SYN_DTLS_Context * ctx,
    const SYN_DTLS_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 Engine configuration.
transport Underlying transport (UDP, Socket, Serial).
rx_buf Caller-allocated buffer for incoming datagrams.
rx_buf_size Size of rx_buf in bytes.
tx_buf Caller-allocated buffer for outgoing datagrams.
tx_buf_size Size of tx_buf in bytes.

Returns:

true on success, false on invalid parameters.

function syn_dtls_recv¶

Receive and decrypt a DTLS 1.3 datagram record.

bool syn_dtls_recv (
    SYN_DTLS_Context * ctx,
    uint8_t * data,
    size_t max_len,
    size_t * out_len
)

Parameters:

ctx Established DTLS context.
data Output buffer for decrypted application data.
max_len Capacity of output buffer.
out_len [out] Actual decrypted payload length.

Returns:

true if valid uncorrupted, non-replayed record received.

function syn_dtls_replay_check¶

Check whether a sequence number is acceptable by the replay window.

bool syn_dtls_replay_check (
    const SYN_DTLS_ReplayWindow * win,
    uint64_t seq
)

Parameters:

win Pointer to replay window.
seq 64-bit reconstructed packet sequence number.

Returns:

true if packet is not a duplicate and is within or ahead of window.

function syn_dtls_replay_update¶

Commit a validated sequence number to the replay window.

void syn_dtls_replay_update (
    SYN_DTLS_ReplayWindow * win,
    uint64_t seq
)

Parameters:

win Pointer to replay window.
seq 64-bit packet sequence number.

function syn_dtls_send¶

Send application data protected by DTLS 1.3 AEAD datagram record.

bool syn_dtls_send (
    SYN_DTLS_Context * ctx,
    const uint8_t * data,
    size_t len
)

Parameters:

ctx Established DTLS context.
data Application data buffer.
len Length in bytes.

Returns:

true if encrypted record was sent.

function syn_dtls_task¶

Non-blocking DTLS background task (Protothread).

SYN_PT_Status syn_dtls_task (
    SYN_PT * pt,
    SYN_Task * task
)

Parameters:

pt Pointer to task protothread.
task Pointer to scheduler task context.

Returns:

SYN_PT_Status.

Macro Definition Documentation¶

define SYN_DTLS_RECORD_MAX_PAYLOAD¶

Maximum DTLS datagram record payload size in bytes (2048).

#define SYN_DTLS_RECORD_MAX_PAYLOAD `2048U`

define SYN_DTLS_REPLAY_WINDOW_SIZE¶

Size of anti-replay sliding window in packets (64).

#define SYN_DTLS_REPLAY_WINDOW_SIZE `64U`

define SYN_DTLS_SECRET_LEN¶

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

#define SYN_DTLS_SECRET_LEN `48U`

define SYN_DTLS_UNIFIED_CID_BIT¶

#define SYN_DTLS_UNIFIED_CID_BIT `0x10U`

Bit 4: Connection ID present

define SYN_DTLS_UNIFIED_EPOCH_MASK¶

#define SYN_DTLS_UNIFIED_EPOCH_MASK `0x03U`

Bits 1..0: Epoch (0..3)

define SYN_DTLS_UNIFIED_FIXED_BIT¶

#define SYN_DTLS_UNIFIED_FIXED_BIT `0x20U`

DTLS 1.3 Unified Header Flags Bit 5: Must be 1 for DTLS 1.3 unified record

define SYN_DTLS_UNIFIED_LEN_BIT¶

#define SYN_DTLS_UNIFIED_LEN_BIT `0x04U`

Bit 2: Length field present

define SYN_DTLS_UNIFIED_SEQ_16BIT¶

#define SYN_DTLS_UNIFIED_SEQ_16BIT `0x08U`

Bit 3: 16-bit sequence number (0 = 8-bit)

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