SSL_NEW_LISTENER(3ossl) OpenSSL SSL_NEW_LISTENER(3ossl)
NAME
SSL_new_listener, SSL_new_listener_from, SSL_is_listener,
SSL_get0_listener, SSL_listen, SSL_accept_connection,
SSL_get_accept_connection_queue_len, SSL_new_from_listener,
SSL_ACCEPT_CONNECTION_NO_BLOCK - SSL object interface for abstracted
connection acceptance
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);
#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
The SSL_new_listener(3) function creates a listener SSL object.
Listener SSL objects are specialised to only accept network connections
in a protocol- agnostic manner. They cannot be used, for example, for
sending or receiving data using SSL_write_ex(3) or SSL_read_ex(3). In
general, only those functions expressly documented as being supported
on a listener SSL object are available.
The SSL_new_listener_from() function creates a listener SSL object
which is subordinate to a QUIC domain SSL object ssl. See
SSL_new_domain(3) and openssl-quic-concurrency(7) for details on QUIC
domain SSL objects.
A listener SSL object supports the following operations:
o Standard reference counting and free operations, such as
SSL_up_ref(3) and SSL_free(3);
o Network BIO configuration operations, such as SSL_set_bio(3);
o Event processing and polling enablement APIs such as
SSL_handle_events(3), SSL_get_event_timeout(3),
SSL_get_rpoll_descriptor(3), SSL_get_wpoll_descriptor(3),
SSL_net_read_desired(3) and SSL_net_write_desired(3);
o Certain configurable parameters described in SSL_get_value_uint(3)
(see SSL_get_value_uint(3) for details);
o Accepting network connections using the functions documented in
this manual page, such as SSL_accept_connection().
The basic workflow of using a listener object is as follows:
SSL_new_listener(3) using a
SSL_CTX which uses a supported SSL_METHOD (such as
OSSL_QUIC_server_method(3));
o Configure appropriate network BIOs using SSL_set_bio(3) on the
listener SSL object;
o Configure the blocking mode using SSL_set_blocking_mode(3);
o 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.
The SSL_is_listener() function returns 1 if and only if a SSL object is
a listener SSL object.
The SSL_get0_listener() function returns a listener object which is
related to the given SSL object, if there is one. For a listener
object, this is the same object (the function returns its argument).
For a connection object which was created by a listener object, that
listener object is returned. If the ssl argument is an SSL object which
is not a listener object and which is not descended from a listener
object (e.g. a connection obtained using SSL_accept_connection()) or
indirectly from a listener object (e.g. a QUIC stream SSL object
obtained using SSL_accept_stream() called on a connection obtained
using SSL_accept_connection()) the return value is NULL. See NOTES
below for caveats related to pending SSL connections on a QUIC
listener's accept queue.
The SSL_listen() function begins monitoring the listener ssl for
incoming connections. Appropriate BIOs must have been configured before
calling SSL_listen(), along with any other needed configuration for the
listener SSL object. It is typically not necessary to call SSL_listen()
because it will be called automatically on the first call to
SSL_accept_connection(). However, SSL_listen() may be called explicitly
if it is desired to control precisely when the listening process
begins, or to ensure that no errors occur when starting to listen for
connections. After a call to SSL_listen() (or SSL_accept_connection())
succeeds. The SSL_listen() function is idempotent, subsequent calls on
the same ssl object are no-ops. This call is supported only on listener
SSL objects.
The SSL_accept_connection() call is supported only on a listener SSL
object and accepts a new incoming connection. A new SSL object
representing the accepted connection is created and returned on
success. 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 may use the function SSL_is_init_finished(3) to determine this. You
may call the functions 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 specified, the call does not block even if
the listener SSL object is configured in blocking mode.
The SSL_get_accept_connection_queue_len() call 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, the actual number of connections that will ultimately be
returned may be different.
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) (see
"CLIENT-ONLY USAGE"). It is expected that the listener interface, which
provides an abstracted API for connection acceptance, will be expanded
to support other protocols, such as TLS over TCP, plain TCP or DTLS in
future.
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
It is also possible to use the listener interface without accepting any
connections and without listening for connections. This can be useful
in circumstances where it is desirable for 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.
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(3) 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. 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.
The SSL_new_from_listener() function creates a client connection under
a given listener SSL object. For QUIC, it is also possible to use
SSL_new_from_listener(), leading to a UDP network endpoint which has
both incoming and outgoing connections.
The flags argument of SSL_new_from_listener() is reserved and must be
set to 0.
RETURN VALUES
SSL_new_listener(3) 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_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.
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. 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(). As 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. This can be used as an indicator
within the callback that the referenced SSL object has not yet been
accepted.
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.
COPYRIGHT
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 file LICENSE in the source distribution or at
<https://www.openssl.org/source/license.html>.
3.5.1 2025-07-02 SSL_NEW_LISTENER(3ossl)
openssl 3.5.1 - Generated Sat Aug 2 04:21:29 CDT 2025