.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SSL_NEW_LISTENER 3SSL"
.TH SSL_NEW_LISTENER 3SSL 2025-04-08 3.5.0 OpenSSL
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH 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
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBSSL_new_listener()\fR 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 \fBSSL_write_ex\fR\|(3) or \fBSSL_read_ex\fR\|(3). In general, only those functions
expressly documented as being supported on a listener SSL object are available.
.PP
The \fBSSL_new_listener_from()\fR function creates a listener SSL object which is
subordinate to a QUIC domain SSL object \fIssl\fR. See \fBSSL_new_domain\fR\|(3) and
\&\fBopenssl\-quic\-concurrency\fR\|(7) for details on QUIC domain SSL objects.
.PP
A listener SSL object supports the following operations:
.IP \(bu 4
Standard reference counting and free operations, such as \fBSSL_up_ref\fR\|(3) and
\&\fBSSL_free\fR\|(3);
.IP \(bu 4
Network BIO configuration operations, such as \fBSSL_set_bio\fR\|(3);
.IP \(bu 4
Event processing and polling enablement APIs such as \fBSSL_handle_events\fR\|(3),
\&\fBSSL_get_event_timeout\fR\|(3), \fBSSL_get_rpoll_descriptor\fR\|(3),
\&\fBSSL_get_wpoll_descriptor\fR\|(3), \fBSSL_net_read_desired\fR\|(3) and
\&\fBSSL_net_write_desired\fR\|(3);
.IP \(bu 4
Certain configurable parameters described in \fBSSL_get_value_uint\fR\|(3) (see
\&\fBSSL_get_value_uint\fR\|(3) for details);
.IP \(bu 4
Accepting network connections using the functions documented in this manual
page, such as \fBSSL_accept_connection()\fR.
.PP
The basic workflow of using a listener object is as follows:
.IP \(bu 4
Create a new listener object using \fBSSL_new_listener()\fR using a \fBSSL_CTX\fR which
uses a supported \fBSSL_METHOD\fR (such as \fBOSSL_QUIC_server_method\fR\|(3));
.IP \(bu 4
Configure appropriate network BIOs using \fBSSL_set_bio\fR\|(3) on the listener SSL
object;
.IP \(bu 4
Configure the blocking mode using \fBSSL_set_blocking_mode\fR\|(3);
.IP \(bu 4
Accept connections in a loop by calling \fBSSL_accept_connection()\fR. Each returned
SSL object is a valid connection which can be used in a normal manner.
.PP
The \fBSSL_is_listener()\fR function returns 1 if and only if a SSL object is a
listener SSL object.
.PP
The \fBSSL_get0_listener()\fR 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 \fIssl\fR
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
\&\fBSSL_accept_connection()\fR) or indirectly from a listener object (e.g. a QUIC
stream SSL object obtained using \fBSSL_accept_stream()\fR called on a connection
obtained using \fBSSL_accept_connection()\fR) the return value is NULL. See NOTES
below for caveats related to pending SSL connections on a QUIC listener's accept
queue.
.PP
The \fBSSL_listen()\fR function begins monitoring the listener \fIssl\fR for incoming
connections. Appropriate BIOs must have been configured before calling
\&\fBSSL_listen()\fR, along with any other needed configuration for the listener SSL
object. It is typically not necessary to call \fBSSL_listen()\fR because it will be
called automatically on the first call to \fBSSL_accept_connection()\fR. However,
\&\fBSSL_listen()\fR 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 \fBSSL_listen()\fR (or
\&\fBSSL_accept_connection()\fR) succeeds. The \fBSSL_listen()\fR function is idempotent,
subsequent calls on the same \fIssl\fR object are no-ops. This call is supported
only on listener SSL objects.
.PP
The \fBSSL_accept_connection()\fR 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.
.PP
The \fBSSL_ACCEPT_CONNECTION_NO_BLOCK\fR flag may be specified to
\&\fBSSL_accept_connection()\fR. If specified, the call does not block even if the
listener SSL object is configured in blocking mode.
.PP
The \fBSSL_get_accept_connection_queue_len()\fR call returns the number of pending
connections on the \fIssl\fR listener's queue. \fBSSL_accept_connection()\fR 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.
.PP
Currently, listener SSL objects are only supported for QUIC server usage via
\&\fBOSSL_QUIC_server_method\fR\|(3), or QUIC client-only usage via
\&\fBOSSL_QUIC_client_method\fR\|(3) or \fBOSSL_QUIC_client_thread_method\fR\|(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.
.PP
\&\fBSSL_listen()\fR and \fBSSL_accept_connection()\fR are "I/O" functions, meaning that they
update the value returned by \fBSSL_get_error\fR\|(3) if they fail.
.SH "CLIENT-ONLY USAGE"
.IX Header "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.
.PP
To disable client address validation on a listener SSL object, the flag
\&\fBSSL_LISTENER_FLAG_NO_VALIDATE\fR may be passed in the flags field of both
\&\fBSSL_new_listener()\fR and \fBSSL_new_listener_from()\fR.  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.
.PP
The \fBSSL_new_from_listener()\fR function creates a client connection under a given
listener SSL object. For QUIC, it is also possible to use
\&\fBSSL_new_from_listener()\fR, leading to a UDP network endpoint which has both
incoming and outgoing connections.
.PP
The \fIflags\fR argument of \fBSSL_new_from_listener()\fR is reserved and must be set to
0.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBSSL_new_listener()\fR and \fBSSL_new_listener_from()\fR return a new listener SSL object
or NULL on failure.
.PP
\&\fBSSL_is_listener()\fR returns 1 if its \fIssl\fR argument is a listener object, 0
otherwise.
.PP
\&\fBSSL_get0_listener()\fR returns an SSL object pointer (potentially to the same
object on which it is called) or NULL.
.PP
\&\fBSSL_listen()\fR returns 1 on success or 0 on failure.
.PP
\&\fBSSL_accept_connection()\fR returns a pointer to a new SSL object on success or NULL
on failure. On success, the caller assumes ownership of the reference.
.PP
\&\fBSSL_get_accept_connection_queue_len()\fR returns a nonnegative value, or 0 if the
queue is empty, or called on an unsupported SSL object type.
.PP
\&\fBSSL_new_from_listener()\fR returns a pointer to a new SSL object on success or NULL
on failure. On success, the caller assumes ownership of the reference.
.SH NOTES
.IX Header "NOTES"
\&\fBSSL_get0_listener()\fR behaves somewhat differently in SSL callbacks for QUIC
connections.  As QUIC connections begin TLS handshake operations prior to them
being accepted via \fBSSL_accept_connection()\fR, an application may receive callbacks
for such pending connection prior to acceptance via \fBSSL_accept_connection()\fR.  As
listener association takes place during the accept process, prior to being
returned from \fBSSL_accept_connection()\fR, calls to \fBSSL_get0_listener()\fR 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBOSSL_QUIC_server_method\fR\|(3), \fBSSL_free\fR\|(3), \fBSSL_set_bio\fR\|(3),
\&\fBSSL_handle_events\fR\|(3), \fBSSL_get_rpoll_descriptor\fR\|(3),
\&\fBSSL_set_blocking_mode\fR\|(3)
.SH HISTORY
.IX Header "HISTORY"
These functions were added in OpenSSL 3.5.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved.
.PP
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>.