TLS API (ytls)

TLS abstraction layer for Yuneta. Exposes a single api_tls_t dispatch table so the rest of the codebase stays backend-agnostic — the actual crypto can be provided by OpenSSL or mbed-TLS.

Selecting a backend¶

The backend is chosen at compile time via .config (Kconfig):

CONFIG_HAVE_OPENSSL=y     # default
CONFIG_HAVE_MBEDTLS=y     # alternative (≈3× smaller static binaries)

The macro TLS_LIBRARY_NAME (defined in ytls.h) expands to "openssl" or "mbedtls". Always use this macro in configuration strings instead of a hard-coded literal:

"'crypto': { 'library': '" TLS_LIBRARY_NAME "', ... }"

Backend notes — mbed-TLS v4.0¶

psa_crypto_init() must be called before any crypto operation; it initialises the PSA RNG, so mbedtls_ssl_conf_rng is no longer needed.
mbedtls_pk_parse_keyfile(ctx, path, password) — 3 arguments in v4.0 (f_rng / p_rng removed).
Use mbedtls_ssl_is_handshake_over(&ssl) to check handshake state instead of inspecting the return value of mbedtls_ssl_handshake.
set_trace() implementations must be silent — they must never emit gobj_log_info calls. Tests capture INFO-level logs and any extra message breaks the expected-results comparison.

Password hashing — cross-backend compatibility¶

hash_password() in c_authz.c uses PBKDF2-HMAC (RFC 2898 / PKCS#5). Both backends implement the identical standard:

OpenSSL → PKCS5_PBKDF2_HMAC()
mbed-TLS → mbedtls_pkcs5_pbkdf2_hmac_ext()

The only non-deterministic part is salt generation (gen_salt()), which uses RAND_bytes() (OpenSSL) or psa_generate_random() (mbed-TLS). Both produce cryptographically strong random bytes; the algorithm result is independent of which RNG was used.

Supported digests (PBKDF2)¶

Both backends support sha1, sha256, sha384, sha512. mbed-TLS additionally supports sha3-256, sha3-384, sha3-512. The default is sha512 with 27500 iterations.

Source code¶

Function reference¶

The individual function reference pages are listed in the left-hand sidebar under TLS API.

`ytls_cleanup()`¶

The ytls_cleanup() function releases resources associated with the given TLS context.

void ytls_cleanup(
    hytls ytls
);

Parameters

Key	Type	Description
`ytls`	`hytls`	The TLS context to be cleaned up.

Returns

This function does not return a value.

Notes

Ensure that ytls_cleanup() is called to free resources allocated by ytls_init() to prevent memory leaks.

`ytls_decrypt_data()`¶

ytls_decrypt_data() decrypts encrypted data from a secure connection and delivers the clear data via the on_clear_data_cb callback.

int ytls_decrypt_data(
    hytls       ytls,
    hsskt       sskt,
    gbuffer_t  *gbuf  // owned
);

Parameters

Key	Type	Description
`ytls`	`hytls`	TLS context handle.
`sskt`	`hsskt`	Secure socket handle.
`gbuf`	`gbuffer_t *`	Encrypted data buffer, owned by the function.

Returns

Returns 0 on success, or a negative value on failure.

Notes

The decrypted data is provided through the on_clear_data_cb callback.

`ytls_do_handshake()`¶

ytls_do_handshake() initiates the TLS handshake process for a secure connection, returning the handshake status.

int ytls_do_handshake(
    hytls  ytls,
    hsskt  sskt
);

Parameters

Key	Type	Description
`ytls`	`hytls`	TLS context handle.
`sskt`	`hsskt`	Secure socket handle.

Returns

Returns 1 if the handshake is complete, 0 if it is in progress, and -1 if it fails.

Notes

The callback on_handshake_done_cb will be invoked once upon success or multiple times in case of failure.

`ytls_encrypt_data()`¶

The ytls_encrypt_data() function encrypts the given clear data in gbuf and triggers the on_encrypted_data_cb callback with the encrypted result.

int ytls_encrypt_data(
    hytls       ytls,
    hsskt       sskt,
    gbuffer_t  *gbuf  // owned
);

Parameters

Key	Type	Description
`ytls`	`hytls`	TLS context handle.
`sskt`	`hsskt`	Secure socket handle.
`gbuf`	`gbuffer_t *`	Buffer containing the clear data to be encrypted. Ownership is transferred.

Returns

Returns 0 on success, or a negative value on failure.

Notes

The encrypted data is delivered asynchronously via the on_encrypted_data_cb callback.

`ytls_flush()`¶

ytls_flush() flushes both clear and encrypted data in the secure connection.

int ytls_flush(
    hytls  ytls,
    hsskt  sskt
);

Parameters

Key	Type	Description
`ytls`	`hytls`	TLS context handle.
`sskt`	`hsskt`	Secure socket handle.

Returns

Returns 0 on success, or a negative value on failure.

Notes

This function ensures that any pending clear or encrypted data is processed and sent.

`ytls_free_secure_filter()`¶

The ytls_free_secure_filter() function releases the resources associated with a secure filter created by ytls_new_secure_filter().

void ytls_free_secure_filter(
    hytls  ytls,
    hsskt  sskt
);

Parameters

Key	Type	Description
`ytls`	`hytls`	The TLS context managing the secure filter.
`sskt`	`hsskt`	The secure socket filter to be freed.

Returns

This function does not return a value.

Notes

Ensure that ytls_shutdown() is called before freeing the secure filter to properly close the connection.

`ytls_get_last_error()`¶

Retrieves the last error message associated with the given secure socket sskt in the TLS context ytls.

const char *ytls_get_last_error(
    hytls  ytls,
    hsskt  sskt
);

Parameters

Key	Type	Description
`ytls`	`hytls`	The TLS context from which to retrieve the last error.
`sskt`	`hsskt`	The secure socket whose last error message is to be retrieved.

Returns

A pointer to a string containing the last error message, or NULL if no error has occurred.

Notes

The returned error message is managed internally and should not be freed by the caller.

`ytls_init()`¶

ytls_init() initializes a TLS context using the specified configuration and mode (server or client).

hytls ytls_init(
    hgobj     gobj,
    json_t   *jn_config,  // not owned
    BOOL      server
);

Parameters

Key	Type	Description
`gobj`	`hgobj`	The GObj context in which the TLS instance will operate.
`jn_config`	`json_t *`	A JSON object containing TLS configuration parameters. This object is not owned by the function.
`server`	`BOOL`	A boolean flag indicating whether the TLS context should be initialized in server mode (`TRUE`) or client mode (`FALSE`).

Returns

Returns a handle to the newly created TLS context (hytls) on success, or NULL on failure.

Notes

The jn_config parameter should include necessary TLS settings such as certificates, ciphers, and buffer sizes. See the structure documentation for valid configuration fields.

`ytls_new_secure_filter()`¶

ytls_new_secure_filter() creates a new secure filter for handling encrypted communication using a TLS context.

hsskt ytls_new_secure_filter(
    hytls ytls,
    int (*on_handshake_done_cb)(void *user_data, int error),
    int (*on_clear_data_cb)(
        void *user_data,
        gbuffer_t *gbuf  // must be decref
    ),
    int (*on_encrypted_data_cb)(
        void *user_data,
        gbuffer_t *gbuf  // must be decref
    ),
    void *user_data
);

Parameters

Key	Type	Description
`ytls`	`hytls`	The TLS context used to create the secure filter.
`on_handshake_done_cb`	`int ()(void user_data, int error)`	Callback function invoked when the handshake process completes. The `error` parameter indicates success (0) or failure (non-zero).
`on_clear_data_cb`	`int ()(void user_data, gbuffer_t *gbuf)`	Callback function invoked when decrypted data is available. The `gbuf` parameter must be decremented (`decref`) after use.
`on_encrypted_data_cb`	`int ()(void user_data, gbuffer_t *gbuf)`	Callback function invoked when encrypted data is available. The `gbuf` parameter must be decremented (`decref`) after use.
`user_data`	`void *`	User-defined data passed to the callback functions.

Returns

Returns an hsskt handle representing the newly created secure filter, or NULL on failure.

Notes

The secure filter manages encrypted communication and invokes the provided callbacks for handshake completion, clear data reception, and encrypted data transmission.

`ytls_set_trace()`¶

Enables or disables tracing for the given secure socket sskt in the TLS context ytls.

void ytls_set_trace(
    hytls  ytls,
    hsskt  sskt,
    BOOL   set
);

Parameters

Key	Type	Description
`ytls`	`hytls`	The TLS context.
`sskt`	`hsskt`	The secure socket for which tracing is to be set.
`set`	`BOOL`	If `TRUE`, enables tracing; if `FALSE`, disables tracing.

Returns

This function does not return a value.

Notes

Tracing provides verbose output for debugging purposes. It should be used with caution in production environments.

`ytls_shutdown()`¶

The ytls_shutdown() function terminates a secure connection associated with the given hsskt session within the specified hytls context.

void ytls_shutdown(
    hytls ytls,
    hsskt sskt
);

Parameters

Key	Type	Description
`ytls`	`hytls`	The TLS context managing the secure connection.
`sskt`	`hsskt`	The secure socket session to be shut down.

Returns

This function does not return a value.

Notes

After calling ytls_shutdown(), the secure session sskt should no longer be used.

`ytls_version()`¶

Retrieves the version string of the TLS implementation used by ytls_version().

const char *ytls_version(
    hytls ytls
);

Parameters

Key	Type	Description
`ytls`	`hytls`	Handle to the TLS context.

Returns

A string representing the version of the TLS implementation.

Notes

The returned string is managed internally and should not be freed by the caller.

Selecting a backend¶

Backend notes — mbed-TLS v4.0¶

Password hashing — cross-backend compatibility¶

Supported digests (PBKDF2)¶

Source code¶

Function reference¶

ytls_cleanup()¶

ytls_decrypt_data()¶

ytls_do_handshake()¶

ytls_encrypt_data()¶

ytls_flush()¶

ytls_free_secure_filter()¶

ytls_get_last_error()¶

ytls_init()¶

ytls_new_secure_filter()¶

ytls_set_trace()¶

ytls_shutdown()¶

ytls_version()¶

`ytls_cleanup()`¶

`ytls_decrypt_data()`¶

`ytls_do_handshake()`¶

`ytls_encrypt_data()`¶

`ytls_flush()`¶

`ytls_free_secure_filter()`¶

`ytls_get_last_error()`¶

`ytls_init()`¶

`ytls_new_secure_filter()`¶

`ytls_set_trace()`¶

`ytls_shutdown()`¶

`ytls_version()`¶