Skip to main content
Version: 0.1.23

TLS component

The NoxTLS TLS component implements Transport Layer Security (TLS) and Datagram TLS (DTLS) for secure client and server connections. It supports TLS 1.0, 1.1, 1.2, and 1.3, and DTLS 1.2 and 1.3.

Supported versions and features​

ProtocolVersionsKey exchangeCiphers
TLS1.0–1.3RSA, ECDHE, DHE, PSK, ECDHE-PSKAES-GCM/CCM, ChaCha20-Poly1305, AES-CBC, ARIA
DTLS1.2, 1.3Same as TLSSame as TLS
  • TLS 1.3: Full handshake, session resumption (tickets), 0-RTT early data, PSK and ECDHE-PSK, client authentication (mTLS), ALPN, SNI.
  • TLS 1.2: ECDHE-RSA, DHE-RSA, ECDHE-ECDSA cipher suites; renegotiation (RFC 5746); Encrypt-then-MAC, Extended Master Secret.
  • DTLS: Fragmentation, retransmission, cookie exchange (Hello Verify Request), replay protection; DTLS 1.3 uses the unified header and connection ID (RFC 9147).

Architecture​

  • Base context (tls_context_t) holds role (client/server), I/O callbacks, and state. TLS 1.2 and 1.3 use version-specific contexts that extend the DTLS/TLS base.
  • I/O is callback-based: you provide tls_send_callback_t and tls_recv_callback_t so the library sends and receives records over your transport (sockets, etc.).
  • Server version negotiation: use tls_accept_auto to accept a Client Hello and route to the right TLS 1.2 or 1.3 handler.

Typical usage​

TLS client (TLS 1.2 or 1.3)​

  1. Create a version-specific context: tls12_context_init or tls13_context_init.
  2. Set I/O callbacks with noxtls_tls_set_io_callbacks (and optional time callback).
  3. (Optional) Set SNI: ctx->base.server_name / server_name_len (TLS 1.2) or same for TLS 1.3.
  4. (Optional) For mutual TLS (TLS 1.3): tls13_set_client_cert (or ECDSA/Ed25519 variants).
  5. Call tls12_connect or tls13_connect to run the handshake.
  6. Use tls12_send / tls12_recv or tls13_send / tls13_recv for application data.
  7. Shut down with tls12_close or tls13_close, then tls12_context_free or tls13_context_free.

TLS server (TLS 1.2 or 1.3)​

  1. Create a context with tls12_context_init or tls13_context_init.
  2. Set I/O callbacks (and optional time callback).
  3. Set server certificate: assign server_cert / server_cert_len (DER), and for TLS 1.2 with ECDHE-RSA/DHE-RSA set the server private key with tls12_set_server_private_rsa; for TLS 1.3 use tls13_set_server_private_rsa.
  4. Call tls12_accept or tls13_accept to run the handshake.
  5. Use send/recv for application data; close and free when done.

Server with automatic version negotiation​

  1. Allocate a tls_context_t plus tls12_context_t and tls13_context_t.
  2. Set I/O on the base context; initialize both TLS 1.2 and TLS 1.3 contexts and configure certificates/keys for each.
  3. Read the first record (Client Hello); call tls_accept_auto with the base context and the two version-specific contexts. It detects the version and completes the handshake on the appropriate context.
  4. Use the negotiated context (TLS 1.2 or 1.3) for send/recv and close.

DTLS​

Use dtls12_context_init or dtls13_context_init. Set MTU and retransmission with dtls_set_mtu and dtls_set_retransmit. Then use the same connect/accept and send/recv pattern as TLS; the library handles fragmentation and retransmission.

Configuration​

API reference​

  • TLS API (common) — Base context, I/O callbacks, record types, constants, version detection, and extension parsing.
  • TLS 1.2 API — TLS 1.2 context, connect/accept, send/recv, handshake steps, and server key/certificate setup.
  • TLS 1.3 API — TLS 1.3 context, connect/accept, early data, PSK, client auth, and session resumption.
  • DTLS API — DTLS context, MTU, retransmission, fragmentation, and cookie handling.

Sample applications​