SSL_NEW_LISTENER(3SSL)

📦
version 4.0.3 · 2 versions
, in ubuntu stonking

🎀 SSL_NEW_LISTENER 🎀

okay bestie, gather round, because this is the OpenSSL manual page for SSL_new_listener, SSL_new_listener_from, SSL_is_listener, SSL_get0_listener, SSL_listen, SSL_listen_ex, SSL_accept_connection, SSL_get_accept_connection_queue_len, SSL_new_from_listener and the SSL_ACCEPT_CONNECTION_NO_BLOCK macro — aka the whole SSL object interface for abstracted connection acceptance. it's giving "listeners are their own little creature and they do exactly one job" and honestly? obsessed. 💅

✨ SYNOPSIS ✨

#include <openssl/ssl.h>

SSL *SSL_new_listener(SSL_CTX *ctx, uint64_t flags);
SSL *SSL_new_listener_from(SSL *ssl, uint64_t flags);

int SSL_is_listener(SSL *ssl);
SSL *SSL_get0_listener(SSL *ssl);

int SSL_listen(SSL *ssl);
int SSL_listen_ex(SSL *ssl, SSL *new_conn);

#define SSL_ACCEPT_CONNECTION_NO_BLOCK
SSL *SSL_accept_connection(SSL *ssl, uint64_t flags);

size_t SSL_get_accept_connection_queue_len(SSL *ssl);

SSL *SSL_new_from_listener(SSL *ssl, uint64_t flags);

🌸 DESCRIPTION 🌸

so SSL_new_listener() makes you a listener SSL object. and these little guys are super specialised — all they do is accept network connections in a protocol-agnostic way. that's the vibe. they literally cannot be used for stuff like sending or receiving data with SSL_write_ex(3) or SSL_read_ex(3). like, not their lane, not their problem. in general, only the functions that are expressly documented as supported on a listener SSL object are available. periodt.

SSL_new_listener_from() makes a listener SSL object that's subordinate to a QUIC domain SSL object called ssl. if you wanna know the lore on QUIC domain SSL objects, go read SSL_new_domain(3) and openssl-quic-concurrency(7). 🦋

A listener SSL object supports the following operations:

The basic workflow of using a listener object is as follows:

  • Create a new listener object using SSL_new_listener() using a SSL_CTX which uses a supported SSL_METHOD (such as OSSL_QUIC_server_method(3));
  • Configure appropriate network BIOs using SSL_set_bio(3) on the listener SSL object;
  • Configure the blocking mode using SSL_set_blocking_mode(3);
  • Accept connections in a loop by calling SSL_accept_connection(). Each returned SSL object is a valid connection which can be used in a normal manner.

SSL_is_listener() returns 1 if and only if a SSL object is a listener SSL object. cute little identity check. 🫶

SSL_get0_listener() hands you back a listener object that's related to the given SSL object, if there even is one. for a listener object, this is the same object (so yeah, the function just returns its own argument, main character energy 👑). for a connection object that was created by a listener object, that listener object gets returned. and if the ssl argument is an SSL object that is not a listener object and is not descended from a listener object (e.g. a connection you got using SSL_accept_connection()) or indirectly from a listener object (e.g. a QUIC stream SSL object you got using SSL_accept_stream() called on a connection obtained using SSL_accept_connection()) — then the return value is NULL. sad but true. 💀 if you want the caveats about pending SSL connections chillin' on a QUIC listener's accept queue, scroll to NOTES below.

SSL_listen() starts monitoring the listener ssl for incoming connections. you've gotta have configured the appropriate BIOs before calling SSL_listen(), plus any other config the listener SSL object needs. and ngl, you usually don't have to call SSL_listen() at all — it gets called automatically on the first call to SSL_accept_connection(). 🙈 but you can call it explicitly if you want to control precisely when the listening process begins, or if you want to make sure no errors happen while starting to listen for connections. After a call to SSL_listen() (or SSL_accept_connection()) succeeds. and SSL_listen() is idempotent, meaning subsequent calls on the same ssl object are no-ops. this call is supported only on listener SSL objects. no cap.

SSL_listen_ex() behaves in a similar fashion to DTLSv1_listen(3) in that it polls a listening SSL object, and, if a new connection is available, writes that connection into the SSL object pointed to by new_conn. heads up though: once a connection is returned from a listener via this call, accepting connections via SSL_accept_connection(3) is no longer permissible, and will result in an error. also note that many calls into the QUIC api may trigger the quic reactor (such as SSL_poll(3)), and will set the port into a mode in which SSL_accept_connection(3) is assumed. to avoid this, it's recommended that, if you want to use SSL_listen_ex, it is the first I/O call made to the SSL object to which the port is attached. first. literally first. 🚨

Likewise, if a listener has accepted a connection via SSL_accept_connection(3), it is impermissible to accept connections via SSL_listen_ex(). also also: SSL objects passed in the new_conn parameter to SSL_listen_ex() must be created using OSSL_QUIC_method(3) or OSSL_QUIC_server_method(3). them's the rules bestie.

SSL_accept_connection() is supported only on a listener SSL object, and it accepts a new incoming connection. a brand new SSL object representing the accepted connection is created and returned on success — baby just dropped ✨. if no incoming connection is available and the listener SSL object is configured in nonblocking mode, NULL is returned.

The new SSL object returned from SSL_accept_connection() may or may not have completed its handshake at the point it is returned. optionally, you can use SSL_is_init_finished(3) to determine this. you may call SSL_accept(3), SSL_do_handshake(3) or SSL_handle_events(3) to progress the state of the SSL object towards handshake completion. other "I/O" functions may also implicitly progress the state of the handshake, such as SSL_poll(3), SSL_read(3) and SSL_write(3).

The SSL_ACCEPT_CONNECTION_NO_BLOCK flag may be specified to SSL_accept_connection(). if you specify it, the call does not block even if the listener SSL object is configured in blocking mode. iconic behaviour honestly. 😌

SSL_get_accept_connection_queue_len() returns the number of pending connections on the ssl listener's queue. SSL_accept_connection() returns the next pending connection, removing it from the queue. the returned connection count is a point-in-time value, so the actual number of connections that will ultimately be returned may be different. don't @ me.

Currently, listener SSL objects are only supported for QUIC server usage via OSSL_QUIC_server_method(3), or QUIC client-only usage via OSSL_QUIC_client_method(3) or OSSL_QUIC_client_thread_method(3) (peep "CLIENT-ONLY USAGE" below 👀). the expectation is that the listener interface — which provides an abstracted API for connection acceptance — will get expanded to support other protocols in future, such as TLS over TCP, plain TCP or DTLS. future plans, not present facts, okay?

SSL_listen() and SSL_accept_connection() are "I/O" functions, meaning that they update the value returned by SSL_get_error(3) if they fail.

💜 CLIENT-ONLY USAGE 💜

you can also use the listener interface without accepting any connections and without listening for connections. super useful when you want multiple connections to share the same underlying network resources. for example, multiple outgoing QUIC client connections could be made to use the same underlying UDP socket. sharing is caring. 🌈

To disable client address validation on a listener SSL object, the flag SSL_LISTENER_FLAG_NO_VALIDATE may be passed in the flags field of both SSL_new_listener() and SSL_new_listener_from().

Note that this flag only impacts the sending of retry frames for server address validation. Tokens may still be communicated from the server via NEW_TOKEN frames, which will still be validated on receipt in future connections.

and now the scary part, so listen up: Note that this setting is not recommended and may be dangerous in untrusted environments. not performing address validation exposes the server to malicious clients that may open large numbers of connections and never transact data on them (roughly equivalent to a TCP syn flood attack), which address validation mitigates. so like, don't. 😭

SSL_new_from_listener() creates a client connection under a given listener SSL object. for QUIC, it's also possible to use SSL_new_from_listener(), leading to a UDP network endpoint which has both incoming and outgoing connections. bi panic, but for sockets. 🦋

The flags argument of SSL_new_from_listener() is reserved and must be set to 0. zero. 0. not NULL, not vibes. 🎀

⭐ RETURN VALUES ⭐

  • SSL_new_listener() and SSL_new_listener_from() return a new listener SSL object or NULL on failure.
  • SSL_is_listener() returns 1 if its ssl argument is a listener object, 0 otherwise.
  • SSL_get0_listener() returns an SSL object pointer (potentially to the same object on which it is called) or NULL.
  • SSL_listen() returns 1 on success or 0 on failure.
  • SSL_listen_ex() returns 1 when a new connection was accepted on the new_conn parameter, 0 if no new connection was available at the time of the call, or -1 in the event an internal error occurred, signaling a need to check the error queue.
  • SSL_accept_connection() returns a pointer to a new SSL object on success or NULL on failure. on success, the caller assumes ownership of the reference. it's yours now, take care of it 🫶
  • SSL_get_accept_connection_queue_len() returns a nonnegative value, or 0 if the queue is empty, or called on an unsupported SSL object type.
  • SSL_new_from_listener() returns a pointer to a new SSL object on success or NULL on failure. on success, the caller assumes ownership of the reference.

🔥 NOTES 🔥

SSL_get0_listener() behaves somewhat differently in SSL callbacks for QUIC connections. here's the situation: as QUIC connections begin TLS handshake operations prior to them being accepted via SSL_accept_connection(), an application may receive callbacks for such pending connection prior to acceptance via SSL_accept_connection(). and since listener association takes place during the accept process — prior to being returned from SSL_accept_connection() — calls to SSL_get0_listener() made from such SSL callbacks will return NULL. so you can use that as an indicator within the callback that the referenced SSL object has not yet been accepted. it's giving "not accepted yet, no listener for you." 🙅‍♀️

🌈 SEE ALSO 🌈

OSSL_QUIC_server_method(3), SSL_free(3), SSL_set_bio(3), SSL_handle_events(3), SSL_get_rpoll_descriptor(3), SSL_set_blocking_mode(3)

🌸 HISTORY 🌸

These functions were added in OpenSSL 3.5.

SSL_listen_ex() was added in OpenSSL 4.0

okay bestie so this is the part where the lawyers pop in and we all say thank you to them, because besties who license their open source code are the blueprint, fr fr.

Copyright 2024-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 LICENSE file in the source distribution or at https://www.openssl.org/source/license.html.

bestie I'm gonna be so real with you: the "you may not use this file except in compliance with the License" line is not decorative, it's the whole vibe. read the license, comply with the license, be a main character with a clean paper trail. 💅

and that's a wrap on SSL_NEW_LISTENER(3SSL), no cap. 🫶

take care of those listeners, hydrate, run your SSL_free() when you're done, and remember: ngl, you ate. ✨🦋🌸

SSL_NEW_LISTENER(3SSL) — source: OpenSSL 4.0.3 — dated 2026-09-29. bestie, you're all caught up, periodt. 🎀👑💜

📦 where this page comes from