SSL_CTX_SET_...NDING_CONN_CB(3SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

✨ NAME ✨

SSL_CTX_set_new_pending_conn_cb, SSL_set_new_pending_conn_cb_fn — bestie, this is the callback function that reports when a QUIC connection SSL object gets created 👀💖

From the 3SSL manual, obviously, we stay documented around here 💅

🦋 SYNOPSIS 🦋

typedef int (*SSL_set_new_pending_conn_cb_fn)(SSL_CTX *c, SSL *new_ssl,
                                              void *arg);
void SSL_CTX_set_new_pending_conn_cb(SSL_CTX *c,
                                    SSL_set_new_pending_conn_cb_fn *f,
                                    void *arg);

no cap, that's the whole signature, copy it exactly bestie 🫶

🌸 DESCRIPTION 🌸

okay so SSL_CTX_set_new_pending_conn_cb() sets the new_pending_conn callback function, plus its lil buddy the associated application data arg. 📎

So here's the tea: when you're using the QUIC transport, TLS handshake processing can happen independently from the thread that accepts the connection the handshake is establishing. meaning?? the <italic>SSL</italic> objects representing the connection may get allocated and initialized before anyone even calls SSL_accept_connection(). 😳

That's why this registered callback exists — you can use it to decorate that preallocated <italic>SSL</italic> object, or create other associations with its parent <italic>SSL</italic>, all before a call to SSL_accept_connection(). iconic behavior, honestly. ✨

💖 RETURN VALUES 💖

  • SSL_CTX_set_new_pending_conn_cb() — returns no value. nothing. void. empty. she gives nothing and that's fine 💅
  • SSL_set_new_pending_conn_cb_fn() — returns an <italic>integer</italic> value. 👑
    • A return value of 0 means the QUIC stack must discard this newly created <italic>SSL</italic> object 😭 — which implies the associated new connection will not be available for handling on a subsequent call to SSL_accept_connection().
    • A nonzero return value is treated as success 🔥, letting the new connection get enqueued to the accept queue.

🔍 SEE ALSO 🔍

⚠️ NOTES ⚠️

Callbacks in QUIC connections have some limitations to them that you really should take into consideration when writing an application. not to be dramatic but this part matters 🫣

  • QUIC connections may begin processing prior to when an application calls SSL_accept_connection() on them. As such, it may occur that callbacks are delivered to applications' registered TLS callbacks prior to those <italic>SSL</italic> objects being returned in SSL_accept_connection(). Applications should expect this possibility. fr fr, prepare yourself. 🙈
  • In particular, no references should be held on <italic>SSL</italic> objects passed to callbacks for QUIC connections until such time as they are returned through a call to SSL_accept_connection(). do not hold that reference bestie, I'm begging 😤
the way that these notes are literally the whole plot... read them twice. 💀

🎀 HISTORY 🎀

SSL_CTX_set_new_pending_conn_cb() was added in OpenSSL 3.5 — she's new here but she's already main character energy ⭐

Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. 💜

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>.

and that's the page bestie!! 🧚 this was OpenSSL 4.0.3, dated 2026-09-29 — go forth and register your callbacks responsibly, mwah 💋🍓

📦 where this page comes from