SSL_CTX_SET_...NDING_CONN_CB(3ossl)

💅 SSL_CTX_set_new_pending_conn_cb, SSL_set_new_pending_conn_cb_fn — the callback that tells you a QUIC connection SSL object just got born 🦋

okay so bestie, this is a page from the OpenSSL manuals (the manual name is 3ossl, iykyk) and it's all about one lil' callback. Sit down, grab a strawberry 🍓, we're getting into it.

---

✨ NAME ✨

SSL_CTX_set_new_pending_conn_cb, SSL_set_new_pending_conn_cb_fn — a callback function whose whole job is to report the creation of QUIC connection SSL objects 👑

---

✨ 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);

---

✨ DESCRIPTION ✨

so SSL_CTX_set_new_pending_conn_cb() sets the new_pending_conn callback function, plus the associated application data argument arg. that's the whole setup, no cap.

here's the tea though 🫖 — when you're using the QUIC transport, the TLS handshake processing can happen independently from the thread that accepts the connection that the handshake is establishing. literally not even on the same thread. so that means SSL objects representing the connection may get allocated and initialized before anyone calls SSL_accept_connection().

and that's exactly where this registered callback comes in, bestie: you can use it to decorate that preallocated SSL object, or to create other associations with its parent SSL, all before the call to SSL_accept_connection() goes down. main character prep energy ✨

---

✨ RETURN VALUES ✨

SSL_CTX_set_new_pending_conn_cb() returns no value. it's giving void, it's giving nothing to check.

SSL_set_new_pending_conn_cb_fn() returns an integer value. and the vibes of that integer matter a LOT:

• a return value of 0 means the QUIC stack must discard this newly created SSL object. and yeah — that implies the associated new connection will not be available for handling on a subsequent call to SSL_accept_connection(). gone. poof. 💀
• a nonzero return value is treated as success, which allows the new connection to be enqueued to the accept queue. slay 🌈

---

✨ SEE ALSO ✨

• SSL_set_ex_data(3)

---

✨ NOTES ✨

callbacks in QUIC connections have some limitations to them that you genuinely should take into consideration when you're writing an application. not optional, bestie, read this part 🙈

• 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 SSL objects being returned in SSL_accept_connection(). applications should expect this possibility. it's not a bug, it's the vibe.
• in particular, no references should be held on SSL objects passed to callbacks for QUIC connections until such time as they are returned through a call to SSL_accept_connection. do not hold a reference early. do not pass go. do not collect $200. 🚫

---

✨ HISTORY ✨

SSL_CTX_set_new_pending_conn_cb() was added in OpenSSL 3.5. a relatively fresh icon 🎀

---

✨ COPYRIGHT ✨

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

---

okay that's the whole page, you ate it 💅 this was OpenSSL 3.5.9, dated 2026-09-2, and yes the date really does just cut off like that in the footer, iconic honestly. go forth and register your callback, bestie 🫶🌸