Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
Standard preamble:
========================================================================
..
.... \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
. ds C` "" . ds C' "" 'br\} . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
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'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF ========================================================================
Title "SSL_NEW_LISTENER 3ossl"
way too many mistakes in technical documents.
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 \fBopenssl-quic-concurrency\|(7) for details on QUIC domain SSL objects.
A listener SSL object supports the following operations:
The basic workflow of using a listener object is as follows:
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 \fBSSL_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 \fBSSL_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, \fBSSL_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 \fBSSL_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 \fBSSL_poll\|(3), SSL_read\|(3) and SSL_write\|(3).
The SSL_ACCEPT_CONNECTION_NO_BLOCK flag may be specified to \fBSSL_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 \fBOSSL_QUIC_server_method\|(3), or QUIC client-only usage via \fBOSSL_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.
\fBSSL_listen() and SSL_accept_connection() are "I/O" functions, meaning that they update the value returned by SSL_get_error\|(3) if they fail.
To disable client address validation on a listener SSL object, the flag \fBSSL_LISTENER_FLAG_NO_VALIDATE may be passed in the flags field of both \fBSSL_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. 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 \fBSSL_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.
\fBSSL_is_listener() returns 1 if its ssl argument is a listener object, 0 otherwise.
\fBSSL_get0_listener() returns an SSL object pointer (potentially to the same object on which it is called) or NULL.
\fBSSL_listen() returns 1 on success or 0 on failure.
\fBSSL_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.
\fBSSL_get_accept_connection_queue_len() returns a nonnegative value, or 0 if the queue is empty, or called on an unsupported SSL object type.
\fBSSL_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.
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>.