AxlTls — TLS Support

See the TLS section in AxlNet — Networking for an overview of TLS support including HTTPS server/client examples and security considerations.

Header: <axl/axl-tls.h>

API Reference

Typedefs

typedef struct AxlTlsContext AxlTlsContext

axl-tls.h:

TLS support using mbedTLS. Optional — requires AXL_TLS=1 at build time. When not available, all functions return -1/NULL/false.

Provides:

Self-signed ECDSA P-256 certificate generation
TLS 1.2 server and client contexts
Transparent integration with AxlTcp, AxlHttpServer, AxlHttpClient

if (axl_tls_init() == AXL_OK) {
    void *cert, *key;
    size_t cert_len, key_len;
    axl_tls_generate_self_signed("MyServer", NULL, 0,
                                 &cert, &cert_len, &key, &key_len);
    axl_tls_server_set_cert(cert, cert_len, key, key_len);
    axl_free(cert);
    axl_free(key);
    // HTTP server now supports HTTPS
}

typedef struct AxlTcp AxlTcp

typedef struct AxlLoop AxlLoop

Functions

bool axl_tls_available(void)

Check if TLS support was compiled in.

Returns:: true if AXL_TLS=1 was set at build time.

int axl_tls_init(void)

Initialize the TLS subsystem. Call once at startup.

Returns:: AXL_OK on success, AXL_ERR if TLS not compiled in or init failed.

void axl_tls_cleanup(void): Shut down the TLS subsystem and free global resources.

int axl_tls_generate_self_signed(const char *cn, const AxlIPv4Address *ips, size_t ip_count, void **cert_der, size_t *cert_len, void **key_der, size_t *key_len)

Generate a self-signed ECDSA P-256 certificate.

The certificate includes SubjectAltName entries for localhost and any provided IP addresses. Valid for 10 years. Caller frees cert_der and key_der with axl_free().

Parameters:

cn – Common Name (e.g. “MyServer”)
ips – IP addresses for SAN (may be NULL)
ip_count – number of IP addresses
cert_der – [out] DER-encoded certificate
cert_len – [out] certificate length
key_der – [out] DER-encoded private key
key_len – [out] key length

Returns:

AXL_OK on success, AXL_ERR on failure.

int axl_tls_server_set_cert(const void *cert_der, size_t cert_len, const void *key_der, size_t key_len)

Load a server certificate and private key for TLS.

After this call, TLS accept operations use this certificate.

Parameters:

cert_der – DER-encoded certificate
cert_len – certificate length
key_der – DER-encoded private key
key_len – key length

Returns:

AXL_OK on success, AXL_ERR on failure.

AxlTlsContext *axl_tls_accept(AxlTcp *sock)

Create a TLS server context for an accepted TCP connection.

Wraps the socket for TLS. Call axl_tls_handshake() after to complete the TLS handshake.

Parameters:

sock – accepted TCP socket

Returns:

context, or NULL on failure.

AxlTlsContext *axl_tls_connect(AxlTcp *sock, const char *hostname)

Create a TLS client context for an outbound TCP connection.

hostname is used for SNI (Server Name Indication). Call axl_tls_handshake() after to complete the handshake.

Parameters:

sock – connected TCP socket
hostname – server hostname for SNI

Returns:

context, or NULL on failure.

int axl_tls_handshake(AxlTlsContext *ctx)

Perform or continue a TLS handshake.

May need to be called multiple times if data isn’t available yet.

Parameters:

ctx – TLS context

Returns:

0 on success (handshake complete), 1 if more data needed (call again after recv), -1 on error.

int axl_tls_read(AxlTlsContext *ctx, void *buf, size_t size, size_t *out_len)

Read decrypted data from a TLS connection.

Parameters:

ctx – TLS context
buf – output buffer
size – buffer capacity
out_len – [out] bytes read

Returns:

0 on success, -1 on error, 1 if more data needed.

int axl_tls_write(AxlTlsContext *ctx, const void *data, size_t len)

Write data over a TLS connection.

Encrypts and sends data via the underlying TCP socket.

Parameters:

ctx – TLS context
data – plaintext data
len – data length

Returns:

AXL_OK on success, AXL_ERR on error.

int axl_tls_write_async(AxlTlsContext *ctx, const void *data, size_t len, AxlLoop *loop, AxlTcpCallback cb, void *cb_data)

Async write over a TLS connection.

Encrypts data synchronously, then sends the ciphertext asynchronously via axl_tcp_send_async on the given loop. The callback fires when the send completes. One-shot — the callback’s bool return is ignored (send owns its buffer; each write needs a fresh call).

Parameters:

ctx – TLS context
data – plaintext data
len – data length
loop – event loop
cb – completion callback
cb_data – opaque context

Returns:

AXL_OK if initiated, AXL_ERR on failure.

void axl_tls_stage_data(AxlTlsContext *ctx, const void *data, size_t len)

Stage received TCP data for TLS processing.

Points the TLS BIO recv callback at the provided buffer (zero-copy). Call before axl_tls_handshake() or axl_tls_read().

Parameters:

ctx – TLS context
data – received TCP data
len – data length

void axl_tls_free(AxlTlsContext *ctx)

Free a TLS context. Sends close_notify. NULL-safe.

Parameters:

ctx – context to free