1=pod 2 3=head1 NAME 4 5SSL_new_listener, SSL_new_listener_from, SSL_is_listener, SSL_get0_listener, 6SSL_listen, 7SSL_accept_connection, SSL_get_accept_connection_queue_len, 8SSL_new_from_listener, 9SSL_ACCEPT_CONNECTION_NO_BLOCK - SSL object interface for abstracted connection 10acceptance 11 12=head1 SYNOPSIS 13 14 #include <openssl/ssl.h> 15 16 SSL *SSL_new_listener(SSL_CTX *ctx, uint64_t flags); 17 SSL *SSL_new_listener_from(SSL *ssl, uint64_t flags); 18 19 int SSL_is_listener(SSL *ssl); 20 SSL *SSL_get0_listener(SSL *ssl); 21 22 int SSL_listen(SSL *ssl); 23 24 #define SSL_ACCEPT_CONNECTION_NO_BLOCK 25 SSL *SSL_accept_connection(SSL *ssl, uint64_t flags); 26 27 size_t SSL_get_accept_connection_queue_len(SSL *ssl); 28 29 SSL *SSL_new_from_listener(SSL *ssl, uint64_t flags); 30 31=head1 DESCRIPTION 32 33The SSL_new_listener() function creates a listener SSL object. Listener SSL 34objects are specialised to only accept network connections in a protocol- 35agnostic manner. They cannot be used, for example, for sending or receiving data 36using L<SSL_write_ex(3)> or L<SSL_read_ex(3)>. In general, only those functions 37expressly documented as being supported on a listener SSL object are available. 38 39The SSL_new_listener_from() function creates a listener SSL object which is 40subordinate to a QUIC domain SSL object I<ssl>. See L<SSL_new_domain(3)> and 41L<openssl-quic-concurrency(7)> for details on QUIC domain SSL objects. 42 43A listener SSL object supports the following operations: 44 45=over 4 46 47=item 48 49Standard reference counting and free operations, such as L<SSL_up_ref(3)> and 50L<SSL_free(3)>; 51 52=item 53 54Network BIO configuration operations, such as L<SSL_set_bio(3)>; 55 56=item 57 58Event processing and polling enablement APIs such as L<SSL_handle_events(3)>, 59L<SSL_get_event_timeout(3)>, L<SSL_get_rpoll_descriptor(3)>, 60L<SSL_get_wpoll_descriptor(3)>, L<SSL_net_read_desired(3)> and 61L<SSL_net_write_desired(3)>; 62 63=item 64 65Certain configurable parameters described in L<SSL_get_value_uint(3)> (see 66L<SSL_get_value_uint(3)> for details); 67 68=item 69 70Accepting network connections using the functions documented in this manual 71page, such as SSL_accept_connection(). 72 73=back 74 75The basic workflow of using a listener object is as follows: 76 77=over 4 78 79=item 80 81Create a new listener object using SSL_new_listener() using a B<SSL_CTX> which 82uses a supported B<SSL_METHOD> (such as L<OSSL_QUIC_server_method(3)>); 83 84=item 85 86Configure appropriate network BIOs using L<SSL_set_bio(3)> on the listener SSL 87object; 88 89=item 90 91Configure the blocking mode using L<SSL_set_blocking_mode(3)>; 92 93=item 94 95Accept connections in a loop by calling SSL_accept_connection(). Each returned 96SSL object is a valid connection which can be used in a normal manner. 97 98=back 99 100The SSL_is_listener() function returns 1 if and only if a SSL object is a 101listener SSL object. 102 103The SSL_get0_listener() function returns a listener object which is related to 104the given SSL object, if there is one. For a listener object, this is the same 105object (the function returns its argument). For a connection object which was 106created by a listener object, that listener object is returned. If the I<ssl> 107argument is an SSL object which is not a listener object and which is not 108descended from a listener object (e.g. a connection obtained using 109SSL_accept_connection()) or indirectly from a listener object (e.g. a QUIC 110stream SSL object obtained using SSL_accept_stream() called on a connection 111obtained using SSL_accept_connection()) the return value is NULL. See NOTES 112below for caveats related to pending SSL connections on a QUIC listener's accept 113queue. 114 115The SSL_listen() function begins monitoring the listener I<ssl> for incoming 116connections. Appropriate BIOs must have been configured before calling 117SSL_listen(), along with any other needed configuration for the listener SSL 118object. It is typically not necessary to call SSL_listen() because it will be 119called automatically on the first call to SSL_accept_connection(). However, 120SSL_listen() may be called explicitly if it is desired to control precisely when 121the listening process begins, or to ensure that no errors occur when starting to 122listen for connections. After a call to SSL_listen() (or 123SSL_accept_connection()) succeeds. The SSL_listen() function is idempotent, 124subsequent calls on the same I<ssl> object are no-ops. This call is supported 125only on listener SSL objects. 126 127The SSL_accept_connection() call is supported only on a listener SSL object and 128accepts a new incoming connection. A new SSL object representing the accepted 129connection is created and returned on success. If no incoming connection is 130available and the listener SSL object is configured in nonblocking mode, NULL is 131returned. 132 133The new SSL object returned from SSL_accept_connection() may or may not have 134completed its handshake at the point it is returned. Optionally, you may use the 135function L<SSL_is_init_finished(3)> to determine this. You may call the 136functions L<SSL_accept(3)>, L<SSL_do_handshake(3)> or L<SSL_handle_events(3)> to 137progress the state of the SSL object towards handshake completion. Other "I/O" 138functions may also implicitly progress the state of the handshake such as 139L<SSL_poll(3)>, L<SSL_read(3)> and L<SSL_write(3)>. 140 141The B<SSL_ACCEPT_CONNECTION_NO_BLOCK> flag may be specified to 142SSL_accept_connection(). If specified, the call does not block even if the 143listener SSL object is configured in blocking mode. 144 145The SSL_get_accept_connection_queue_len() call returns the number of pending 146connections on the I<ssl> listener's queue. SSL_accept_connection() returns the 147next pending connection, removing it from the queue. The returned connection 148count is a point-in-time value, the actual number of connections that will 149ultimately be returned may be different. 150 151Currently, listener SSL objects are only supported for QUIC server usage via 152L<OSSL_QUIC_server_method(3)>, or QUIC client-only usage via 153L<OSSL_QUIC_client_method(3)> or L<OSSL_QUIC_client_thread_method(3)> (see 154L</CLIENT-ONLY USAGE>). It is expected that the listener interface, which 155provides an abstracted API for connection acceptance, will be expanded to 156support other protocols, such as TLS over TCP, plain TCP or DTLS in future. 157 158SSL_listen() and SSL_accept_connection() are "I/O" functions, meaning that they 159update the value returned by L<SSL_get_error(3)> if they fail. 160 161=head1 CLIENT-ONLY USAGE 162 163It is also possible to use the listener interface without accepting any 164connections and without listening for connections. This can be useful in 165circumstances where it is desirable for multiple connections to share the same 166underlying network resources. For example, multiple outgoing QUIC client 167connections could be made to use the same underlying UDP socket. 168 169To disable client address validation on a listener SSL object, the flag 170B<SSL_LISTENER_FLAG_NO_VALIDATE> may be passed in the flags field of both 171SSL_new_listener() and SSL_new_listener_from(). Note that this flag only 172impacts the sending of retry frames for server address validation. Tokens may 173still be communicated from the server via NEW_TOKEN frames, which will still 174be validated on receipt in future connections. Note that this setting is not 175recommended and may be dangerous in untrusted environments. Not performing 176address validation exposes the server to malicious clients that may open large 177numbers of connections and never transact data on them (roughly equivalent to 178a TCP syn flood attack), which address validation mitigates. 179 180The SSL_new_from_listener() function creates a client connection under a given 181listener SSL object. For QUIC, it is also possible to use 182SSL_new_from_listener(), leading to a UDP network endpoint which has both 183incoming and outgoing connections. 184 185The I<flags> argument of SSL_new_from_listener() is reserved and must be set to 1860. 187 188=head1 RETURN VALUES 189 190SSL_new_listener() and SSL_new_listener_from() return a new listener SSL object 191or NULL on failure. 192 193SSL_is_listener() returns 1 if its I<ssl> argument is a listener object, 0 194otherwise. 195 196SSL_get0_listener() returns an SSL object pointer (potentially to the same 197object on which it is called) or NULL. 198 199SSL_listen() returns 1 on success or 0 on failure. 200 201SSL_accept_connection() returns a pointer to a new SSL object on success or NULL 202on failure. On success, the caller assumes ownership of the reference. 203 204SSL_get_accept_connection_queue_len() returns a nonnegative value, or 0 if the 205queue is empty, or called on an unsupported SSL object type. 206 207SSL_new_from_listener() returns a pointer to a new SSL object on success or NULL 208on failure. On success, the caller assumes ownership of the reference. 209 210=head1 NOTES 211 212SSL_get0_listener() behaves somewhat differently in SSL callbacks for QUIC 213connections. As QUIC connections begin TLS handshake operations prior to them 214being accepted via SSL_accept_connection(), an application may receive callbacks 215for such pending connection prior to acceptance via SSL_accept_connection(). As 216listener association takes place during the accept process, prior to being 217returned from SSL_accept_connection(), calls to SSL_get0_listener() made from 218such SSL callbacks will return NULL. This can be used as an indicator within 219the callback that the referenced SSL object has not yet been accepted. 220 221=head1 SEE ALSO 222 223L<OSSL_QUIC_server_method(3)>, L<SSL_free(3)>, L<SSL_set_bio(3)>, 224L<SSL_handle_events(3)>, L<SSL_get_rpoll_descriptor(3)>, 225L<SSL_set_blocking_mode(3)> 226 227=head1 HISTORY 228 229These functions were added in OpenSSL 3.5. 230 231=head1 COPYRIGHT 232 233Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved. 234 235Licensed under the Apache License 2.0 (the "License"). You may not use 236this file except in compliance with the License. You can obtain a copy 237in the file LICENSE in the source distribution or at 238L<https://www.openssl.org/source/license.html>. 239 240=cut 241