SSL_SET_QUIC_TLS_CBS(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

okay bestie, welcome to SSL_SET_QUIC_TLS_CBS(3ossl) — the OpenSSL manual page that’s all about letting the OpenSSL TLS implementation do the TLS thing for a third party QUIC implementation, and it’s genuinely such a serve. 💅✨

✨ NAME ✨

The whole crew on this page is:

OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn
OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn
OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn
OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn
OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn
OSSL_FUNC_SSL_QUIC_TLS_alert_fn
SSL_set_quic_tls_cbs
SSL_set_quic_tls_transport_params
SSL_set_quic_tls_early_data_enabled

Short version: use the OpenSSL TLS implementation for a third party QUIC implementation. 🫶

🦋 SYNOPSIS 🦋

        #include <openssl/ssl.h>

        /* QUIC TLS callbacks available via an OSSL_DISPATCH table */

        /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND */
        typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn)(SSL *s,
                                                             const unsigned char *buf,
                                                             size_t buf_len,
                                                             size_t *consumed,
                                                             void *arg);

        /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD */
        typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn)(SSL *s,
                                                           const unsigned char **buf,
                                                           size_t *bytes_read,
                                                           void *arg);

        /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD */
        typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn)(SSL *,
                                                                    size_t bytes_read,
                                                                    void *arg);

        /* Function id: OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET */
        typedef int (*OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn)(SSL *s,
                                                           uint32_t prot_level,
                                                           int direction,
                                                           const unsigned char *secret,
                                                           size_t secret_len,
                                                           void *arg);

        /* Function id: OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS */
        typedef int (*OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn)(SSL *s,
                                                           const unsigned char *params,
                                                           size_t params_len,
                                                           void *arg);

        /* Function id: OSSL_FUNC_SSL_QUIC_TLS_ALERT */
        typedef int (*OSSL_FUNC_SSL_QUIC_TLS_alert_fn)(SSL *s,
                                                       unsigned char alert_code,
                                                       void *arg);

        int SSL_set_quic_tls_cbs(SSL *s, const OSSL_DISPATCH *qtdis, void *arg);
        int SSL_set_quic_tls_transport_params(SSL *s,
                                              const unsigned char *params,
                                              size_t params_len);
        int SSL_set_quic_tls_early_data_enabled(SSL *s, int enabled);

🌈 DESCRIPTION 🌈

So here’s the tea: SSL_set_quic_tls_cbs() can replace the standard TLS record layer with a custom record layer for a third party QUIC implementation. For the given SSL object s, you supply a set of callbacks in an OSSL_DISPATCH table via qtdis. The arg parameter gets passed as an argument whenever the various callbacks are called. 🫶

An OSSL_DISPATCH table is an array of OSSL_DISPATCH entries, where each entry is a function id and a function pointer. Terminate the array with an empty entry — that means a 0 function id and a NULL function pointer. No cap. 🧚

Calling SSL_set_quic_tls_cbs() switches off the SSL_OP_ENABLE_MIDDLEBOX_COMPAT option (if it is set). See SSL_set_options(3). It also sets the minimum TLS protocol version to TLS1_3_VERSION. Calling this function with anything other than a TLS connection SSL object is an error. 🚨

Here are the callbacks and what they’re giving:

OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn — function id OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND. Called when CRYPTO frame data should be sent to the peer. The data to send is supplied in the buffer buf, which is of length buf_len. The callback may choose to consume less data than was supplied in the buffer. On successful completion of the callback, the consumed parameter should be populated with the amount of data that the callback consumed. This should be less than or equal to the value in buf_len. CRYPTO data should be sent using the most recent write encryption level set via the OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn callback (if it has been called). 🔥
OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn — function id OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD. Used to receive CRYPTO frame data from the peer. When OpenSSL wants to read data from the peer, this callback is called. The callback should populate *buf with a pointer to a buffer containing CRYPTO data that has been received from the peer. The size of the buffer should be populated in *bytes_read. The buffer should remain valid until OpenSSL calls the OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn callback. CRYPTO frame data is assumed to have been decrypted using the most recent read protection level set via the yield_secret_cb callback (if it has been called). 💀
OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn — function id OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD. Called when data previously read via OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn is no longer required. The bytes_read argument is always equal to the size of the buffer previously provided in the crypto_receive_rcd_cb callback. Only one record at a time will ever be read by OpenSSL. 🫡
OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn — function id OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET. Called when a new secret has been established. The prot_level argument identifies the TLS protection level and will be one of OSSL_RECORD_PROTECTION_LEVEL_NONE, OSSL_RECORD_PROTECTION_LEVEL_EARLY, OSSL_RECORD_PROTECTION_LEVEL_HANDSHAKE or OSSL_RECORD_PROTECTION_LEVEL_APPLICATION. The direction will either be 0 (for the read secret) or 1 (for the write secret). The secret itself will be in the buffer pointed to by secret, and the buffer will be of length secret_len. 👑
OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn — function id OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS. Called when transport parameters have been received from the peer. The parameters are held in the params buffer, which is of length params_len. 🌸
OSSL_FUNC_SSL_QUIC_TLS_alert_fn — function id OSSL_FUNC_SSL_QUIC_TLS_ALERT. Called when OpenSSL is attempting to send an alert to the peer. The code for the alert is supplied in alert_code. 🚨

SSL_set_quic_tls_transport_params() is used to set the transport parameters to be sent by this endpoint. The parameters are in the params buffer, which should be of length params_len. The buffer containing the parameters should remain valid until after the parameters have been sent. This function must have been called by the time the transport parameters need to be sent. For a client this will be before the connection has been initiated. For a server this might typically occur during the got_transport_params_cb. 🎀

SSL_set_quic_tls_early_data_enabled() is used to enable the 0-RTT feature for a third party QUIC implementation. ✨

💅 RETURN VALUES 💅

These functions return 1 on success and 0 on failure.

All of the callbacks should also return 1 on success and 0 on failure. A failure response is fatal to the connection, so bestie, do not treat a 0 like a casual vibe check. 💀

🧚 EXAMPLES 🧚

A call to SSL_set_quic_tls_cbs() might look something like the following, given suitable definitions of the various callback functions:

        const OSSL_DISPATCH qtdis[] = {
            {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND, (void (*)(void))crypto_send_cb},
            {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD,
                (void (*)(void))crypto_recv_rcd_cb},
            {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD,
                (void (*)(void))crypto_release_rcd_cb},
            {OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET,
                (void (*)(void))yield_secret_cb},
            {OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS,
                (void (*)(void))got_transport_params_cb},
            {OSSL_FUNC_SSL_QUIC_TLS_ALERT, (void (*)(void))alert_cb},
            {0, NULL}
         };

        if (!SSL_set_quic_tls_cbs(ssl, qtdis, NULL))
            goto err;

⭐ HISTORY ⭐

These functions were added in OpenSSL 3.5. ⭐

🎀 COPYRIGHT 🎀

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

made with 💖 by OpenSSL 3.5.0, dated 2026-09-25 — go slay your QUIC handshake, bestie 🫶

📦 where this page comes from

opensuse-leap 16.0: openssl-3-doc 3.5.0-160000.11.1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms