Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

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, mbed-TLS, or both.

Selecting backends

One or both backends can be enabled at compile time via .config (Kconfig):

CONFIG_HAVE_OPENSSL=y     # default, full-featured
CONFIG_HAVE_MBEDTLS=y     # lightweight (≈3× smaller static binaries)

When both are enabled, the preferred default is OpenSSL. Each connection can select its backend at runtime via the "library" key in the crypto JSON config (for example "library": "mbedtls" to override the default).

ytls.h is the single source of truth for the backend names:

Use TLS_LIBRARY_NAME directly in C string literals instead of a hard-coded value:

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

root-linux’s yunetas_register_c_core() publishes both names into gobj’s global-variable pool via gobj_add_global_variable(), so kw configs can substitute them at load time:

"crypto": { "library": "(^^__tls_library__^^)" }

This is what keeps gobj-c free of any CONFIG_HAVE_OPENSSL / CONFIG_HAVE_MBEDTLS checks — TLS knowledge lives only in this module.

Backend notes — mbed-TLS v4.0

Password hashing — cross-backend compatibility

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

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

KeyTypeDescription
ytlshytlsThe TLS context to be cleaned up.

Returns

This function does not return a value.

Notes

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


ytls_reload_certificates()

Hot-reloads the TLS certificate material of an existing context without disrupting live connections. Builds a fresh backend state (OpenSSL SSL_CTX or mbed-TLS mbedtls_ssl_config bundle) from the new jn_config, validates it, and atomically swaps it into the ytls handle.

int ytls_reload_certificates(
    hytls    ytls,
    json_t  *jn_config   // not owned
);

Parameters

KeyTypeDescription
ytlshytlsTLS context previously returned by ytls_init().
jn_configjson_t *New crypto config (same keys as ytls_init(): ssl_certificate, ssl_certificate_key, ssl_trusted_certificate, ssl_ciphers, ssl_verify_depth, trace_tls, rx_buffer_size). Not owned by the function.

Returns

0 on success. -1 on failure (for example: a file is missing, the cert and key do not match, or the cert/key is unparseable). On failure the previous context is kept intact — the caller can continue serving traffic with the old material and retry the reload later.

Notes

The old backend state is kept alive, via refcount, for every secure filter (hsskt) created before the reload. New filters created after the reload use the fresh state. Concretely:

This is how Yuneta integrates Let’s Encrypt renewals without dropping active TLS connections. See the cert management guide for the full operational flow.


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

KeyTypeDescription
ytlshytlsTLS context handle.
sskthssktSecure socket handle.
gbufgbuffer_t *Encrypted data buffer, owned by the function.

Returns

Returns 0 on success, and -2222 when the secure socket was freed inside a callback (its owner dropped the connection there: on_clear_data_cb, or on_handshake_done_cb / on_encrypted_data_cb while the handshake runs): touch neither the sskt nor its owner, which is possibly gone too. Returns < -1000 on a TLS error.

int ret = ytls_decrypt_data(ytls, sskt, gbuf);
if(ret == -2222) {
    return;     // the connection ended inside the callback: nothing more to do
}
if(ret < -1000) {
    // TLS error: close the connection
}

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

KeyTypeDescription
ytlshytlsTLS context handle.
sskthssktSecure socket handle.

Returns

Returns 1 if the handshake is complete, 0 if it is in progress, -1 if it fails, and -2222 when the secure socket was freed inside a callback (the owner ended the connection in on_handshake_done_cb, or in on_encrypted_data_cb because the write of the handshake’s bytes was not able to start): touch neither the sskt nor its owner.

int ret = ytls_do_handshake(ytls, sskt);
if(ret == -2222) {
    return;     // the connection ended inside a callback: the gobj may be gone
}
if(ret < 0) {
    // the handshake cannot start: end the connection
}

Notes

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

Freed inside a callback. Any of the three callbacks can free the session (ytls_free_secure_filter()) from inside: C_TCP does, when a write cannot start or a subscriber drops the connection. Each call in progress keeps a marker on its stack, the markers are chained (the calls nest: decrypt, handshake, the flush of the encrypted bytes), and the free clears them all: every call returns -2222 on its way out and never reads the session again. Up to 7.25.21 only on_clear_data_cb was covered, and the backends read the freed session after the other two (tests/c/ytls/test_free_inside_callback, both backends).


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

KeyTypeDescription
ytlshytlsTLS context handle.
sskthssktSecure socket handle.
gbufgbuffer_t *Buffer containing the clear data to be encrypted. Ownership is transferred.

Returns

Returns 0 on success, and -2222 when the secure socket was freed inside a callback (a subscriber of the clear data published while the backend waited dropped the connection, or the write of the encrypted data was not able to start): touch neither the sskt nor its owner. Returns any other 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

KeyTypeDescription
ytlshytlsTLS context handle.
sskthssktSecure socket handle.

Returns

Returns 0 on success, -2222 when the secure socket was freed inside a callback (touch neither the sskt nor its owner), -1 when on_clear_data_cb answered an error, or a value below -1000 on a TLS error.

Notes

This function makes sure that any pending clear or encrypted data is processed and sent. Only a TLS error (below -1000) ends the connection: a -1 is the subscriber’s own answer to the clear data it was handed.

int ret = ytls_flush(priv->ytls, priv->sskt);
if(ret == -2222) {
    return;     // the session was freed inside a callback
}
if(ret < -1000) {
    try_to_stop_yevents(gobj);  // a TLS error
    return;
}

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

KeyTypeDescription
ytlshytlsThe TLS context managing the secure filter.
sskthssktThe secure socket filter to be freed.

Returns

This function does not return a value.

Notes

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


ytls_get_cert_info()

Introspects the certificate currently loaded in the TLS context: the server’s, or a client’s own when the client was given ssl_certificate (mutual TLS, see ytls_get_peer_cert_info()). Used by the view-cert command on TLS listeners and by the yuno-level certificate-expiry monitor.

json_t *ytls_get_cert_info(
    hytls  ytls
);

Parameters

KeyTypeDescription
ytlshytlsTLS context handle.

Returns

A new json_t object owned by the caller, or NULL if no certificate is loaded (a client without one, or a backend that cannot introspect). The caller must json_decref() the returned object.

The returned object contains these keys (same shape across the OpenSSL and mbed-TLS backends):

KeyTypeDescription
subjectstringX.509 subject DN in one-line form (for example /CN=api.example.com).
issuerstringX.509 issuer DN in one-line form. Equal to subject for self-signed certs.
cnstringThe common name of the subject, as utf8 whatever its ASN.1 type (a BMPString or a T61String reads the same on both backends: CN=nodé1 is "nodé1"). Absent when there is none, or when it holds a NUL byte (if the name is cut there, it becomes another name).
dns_nameslistThe DNS names of the subjectAltName extension (empty when it has none). A name with a NUL byte is left out.
not_beforeintegerUnix timestamp of the certificate’s notBefore.
not_afterintegerUnix timestamp of the certificate’s notAfter. Use (not_after - time(NULL)) / 86400 to get days_remaining. A negative value means already expired.
serialstringSerial number as uppercase hex (no colons).
spki_sha256stringThe sha256 of the public key (SPKI, DER), lowercase hex, the same in both backends: the value a peer that pins this key records (see ytls_get_peer_cert_info()).

Notes

Loading an expired certificate does NOT fail — the loader intentionally does not enforce validity at load time (the TLS handshake does). This is what lets the expiry monitor report a negative days_remaining for a cert that needs urgent replacement, instead of the yuno refusing to start at all.


ytls_get_peer_cert_info()

The certificate that the PEER of a connection presented in its handshake: for a server, the client’s (mutual TLS), and for a client, the server’s. It is how a server tells WHO is on the other end, not only that the chain is good. C_TCP puts it in its EV_CONNECTED as peer_cert.

json_t *ytls_get_peer_cert_info(
    hytls  ytls,
    hsskt  sskt
);

Parameters

KeyTypeDescription
ytlshytlsTLS context handle.
sskthssktThe secure filter of the connection, after its handshake.

Returns

A new json_t object owned by the caller, or NULL when the peer presented no certificate. The keys of ytls_get_cert_info(), and:

KeyTypeDescription
verifiedbooleanThe chain of the certificate was verified against the CA of the context (ssl_trusted_certificate, ssl_use_system_ca). false under ssl_verify_mode "optional" for a certificate that did not verify (the handshake completes, with a WARNING), under "request", where the chain is not verified (a CA in the context is not used), and under "none", where nothing is verified.
spki_sha256stringThe sha256 of the public key of the certificate (its SPKI, DER), in lowercase hex. It is the same in both backends, and it is what openssl x509 -in peer.crt -pubkey -noout | openssl pkey -pubin -outform DER | sha256sum gives. It names the KEY: a certificate made again with the same key keeps it.

Notes

A server asks the client for a certificate in three modes:

A client presents a certificate when it is given ssl_certificate and ssl_certificate_key (both backends, and the OpenSSL client loads them since this function exists, and a client whose certificate cannot be loaded is refused, NULL from ytls_init(), not a fatal exit). Trust an identity read here only with verified true, or with a spki_sha256 that you pinned.

Example

A server that requires a client certificate of its own CA, and a client that presents one:

json_t *server_crypto = json_pack("{s:s, s:s, s:s, s:s}",
    "ssl_certificate",          "/yuneta/store/certs/backup.example.com.crt",
    "ssl_certificate_key",      "/yuneta/store/certs/private/backup.example.com.key",
    "ssl_trusted_certificate",  "/yuneta/store/certs/nodes_ca.pem",
    "ssl_verify_mode",          "required"
);
json_t *client_crypto = json_pack("{s:s, s:s, s:s}",
    "ssl_trusted_certificate",  "/yuneta/store/certs/backup_ca.pem",
    "ssl_certificate",          "/yuneta/store/certs/node-b.crt",
    "ssl_certificate_key",      "/yuneta/store/certs/private/node-b.key"
);

/* In the server, after the handshake of a connection: */
json_t *peer = ytls_get_peer_cert_info(ytls, sskt);
if(peer && json_is_true(json_object_get(peer, "verified"))) {
    const char *cn = json_string_value(json_object_get(peer, "cn"));   /* "node-b" */
}
JSON_DECREF(peer)

A server that takes the self-signed certificate of each client as it comes and pins its key ("request"):

json_t *server_crypto = json_pack("{s:s, s:s, s:s}",
    "ssl_certificate",          "/yuneta/store/certs/controlcenter.example.com.crt",
    "ssl_certificate_key",      "/yuneta/store/certs/private/controlcenter.example.com.key",
    "ssl_verify_mode",          "request"
);

/* In the server, after the handshake of a connection: */
json_t *peer = ytls_get_peer_cert_info(ytls, sskt);
const char *spki = peer? json_string_value(json_object_get(peer, "spki_sha256")) : NULL;
if(spki && strcmp(spki, pinned_spki) == 0) {   /* the key recorded for this client */
    /* the client is the one pinned; "verified" is false here, by design */
}
JSON_DECREF(peer)

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

KeyTypeDescription
ytlshytlsThe TLS context from which to retrieve the last error.
sskthssktThe 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 must not be freed by the caller.


ytls_get_system_ca_bundle()

Returns the path of the first OS CA-certificate bundle found on the host, probing the well-known locations across distros (Debian/Ubuntu/Alpine, RHEL/Rocky/Alma/ Fedora, SUSE, BSD). This is what ssl_use_system_ca relies on. It works in fully static binaries, where OpenSSL’s compile-time OPENSSLDIR is not present.

const char *ytls_get_system_ca_bundle(void);

Parameters

This function takes no parameters.

Returns

A pointer to a static string with the bundle path, or NULL if no known bundle exists on the host. The returned string is managed internally and must not be freed.

Notes

Both backends use it: OpenSSL loads the bundle as verify locations, and mbed-TLS (which has no system trust store) parses it instead of falling back to no verification.


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

KeyTypeDescription
gobjhgobjThe GObj context in which the TLS instance will operate.
jn_configjson_t *A JSON object containing TLS configuration parameters. This object is not owned by the function.
serverBOOLA boolean flag indicating whether the TLS context must 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 must include necessary TLS settings such as certificates, ciphers, and buffer sizes. See the structure documentation for valid configuration fields.

ytls_init() is never fatal: it answers NULL, and the process goes on. When the certificate, its key or the ssl_trusted_certificate cannot be loaded (a missing file, a key that does not match), or library names a backend this build does not have, ytls_init() logs ONE ERROR with the cause and returns NULL. This holds for a server as for a client. What fails is that one TLS context, never the yuno: a client’s connection fails, and a server’s owner decides. C_TCP_S never listens without a context: by default (exitOnError) it exits the yuno with code 0, and with exitOnError 0 (the agent’s) it tries again until the files are there and the yuno and its other listeners go on (see A TLS server without its TLS context on its page).

Up to 7.30.17 a server exited the process with code 0 here (LOG_OPT_EXIT_ZERO, the OpenSSL backend always, mbedTLS since 7.30.15), and an unknown library exited it for a client too. Code 0 told the watcher not to relaunch the yuno, so an agent without its pair stayed dead, and on a node with no SSH nothing was able to bring it back. Up to 7.30.14 the mbedTLS backend returned NULL, C_TCP_S listened with no context, and the first peer crashed the yuno.

What the operator sees for a server, for example the agent’s 1993 without /yuneta/agent/certs/yuneta_agent.key:

A hot reload is never fatal either: ytls_reload_certificates() keeps the previous certificates.

json_t *crypto = json_pack("{s:s, s:s, s:s}",
    "library",              "openssl",
    "ssl_certificate",      "/yuneta/agent/certs/localhost.crt",
    "ssl_certificate_key",  "/yuneta/agent/certs/localhost.key"
);
hytls ytls = ytls_init(gobj, crypto, TRUE);   /* a server: no file -> NULL, the ERROR of the cause */
JSON_DECREF(crypto)
if(!ytls) {
    // Error already logged: do not listen, and try again later
}

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  // owned by the callback, whatever it answers
    ),
    int (*on_encrypted_data_cb)(
        void *user_data,
        gbuffer_t *gbuf  // owned by the callback, whatever it answers
    ),
    void *user_data
);

Parameters

KeyTypeDescription
ytlshytlsThe TLS context used to create the secure filter.
on_handshake_done_cbint (*)(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_cbint (*)(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_cbint (*)(void *user_data, gbuffer_t *gbuf)Callback function invoked when encrypted data is available. The gbuf parameter must be decremented (decref) after use.
user_datavoid *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.

The filter is returned “cold”: no handshake is started automatically. Call ytls_do_handshake() right after this function to kick off the TLS handshake. On the client side this emits the ClientHello via on_encrypted_data_cb. On the server side it is a no-op that returns 0 (WANT_READ) until the peer speaks first.


ytls_set_peer_name()

Records the connection’s peer and local socket names on the secure socket sskt so the backend’s default-on TLS diagnostics (for example a rejected handshake) are self-contained — the offending peer is identifiable even with the transport’s connections trace disabled.

void ytls_set_peer_name(
    hytls        ytls,
    hsskt        sskt,
    const char  *peername,
    const char  *sockname
);

Parameters

KeyTypeDescription
ytlshytlsThe TLS context.
sskthssktThe secure socket to annotate.
peernameconst char *Remote address (ip:port). NULL is treated as empty.
socknameconst char *Local address (ip:port). NULL is treated as empty.

Returns

This function does not return a value.

Notes

Optional. ytls never reinterprets the secure filter’s user_data as a gobj, so a caller that does not set the names logs them as empty strings. The transport (c_tcp) calls it right after creating the secure filter.


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

KeyTypeDescription
ytlshytlsThe TLS context.
sskthssktThe secure socket for which tracing is to be set.
setBOOLIf TRUE, enables tracing. If FALSE, disables tracing.

Returns

This function does not return a value.

Notes

Tracing provides verbose output for debugging purposes. It must 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

KeyTypeDescription
ytlshytlsThe TLS context managing the secure connection.
sskthssktThe secure socket session to be stop.

Returns

This function does not return a value.

Notes

After calling ytls_shutdown(), the secure session sskt must 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

KeyTypeDescription
ytlshytlsHandle to the TLS context.

Returns

A string representing the version of the TLS implementation.

Notes

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


openssl_api_tls()

Returns the OpenSSL TLS backend dispatch table.

api_tls_t *openssl_api_tls(void);

Parameters

KeyTypeDescription
--This function does not take any parameters.

Returns

Pointer to the api_tls_t structure with OpenSSL-specific implementations.

Notes


mbed_api_tls()

Returns the mbed-TLS backend dispatch table.

api_tls_t *mbed_api_tls(void);

Parameters

KeyTypeDescription
--This function does not take any parameters.

Returns

Pointer to the api_tls_t structure with mbed-TLS-specific implementations.

Notes