=head1 DESCRIPTION
-The SSL_new_listener() function creates a listener SSL object. A listener SSL
-object differs from an ordinary SSL object in that it is used to provide an
-abstraction for the acceptance of network connections in a protocol-agnostic
-manner. It cannot be used, for example, for sending or receiving data using
-L<SSL_write_ex(3)> or L<SSL_read_ex(3)>. In general, only those functions
+The SSL_new_listener() 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 L<SSL_write_ex(3)> or L<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
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 itself). For a connection object which was created
-by a listener object, that listener object is returned. 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()) returns NULL. Also note
-that pending SSL connections on a QUIC listeners accept queue have some caveats,
-see NOTES below.
-
-The SSL_listen() function begins listening after a listener has been created.
-Appropriate BIOs must have been configured before calling SSL_listen(), along
-with any other needed configuration for the listener SSL object. It is
-ordinarily not needed to call SSL_listen() because it will be called
-automatically on the first call to SSL_accept_connection(). However,
+object (the function returns its argument). For a connection object which was
+created by a listener object, that listener object is returned. If the I<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 I<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, subsequent calls to SSL_listen() are
-idempotent no-ops. This call is supported only on a listener SSL object.
+SSL_accept_connection()) succeeds. The SSL_listen() function is idempotent,
+subsequent calls on the same I<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
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 an informational value
-listing the number of connections waiting to be popped from the queue via calls
-to SSL_accept_connection(). Note that since this may change between subsequent
-API calls to the listener SSL object, it should be used for informational
-purposes only.
+The SSL_get_accept_connection_queue_len() call returns the number of pending
+connections on the I<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
L<OSSL_QUIC_server_method(3)>, or QUIC client-only usage via
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() 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 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 I<flags> argument of SSL_new_from_listener() is reserved and must be set to
0.
SSL_new_listener() and SSL_new_listener_from() return a new listener SSL object
or NULL on failure.
-SSL_is_listener() returns 0 or 1 depending on the type of the SSL object on
-which it is called.
+SSL_is_listener() returns 1 if its I<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_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
-called on an unsupported SSL object type.
+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.
=head1 HISTORY
-These functions were added in OpenSSL @VERSION_QUIC_SERVER@.
+These functions were added in OpenSSL 3.5.
=head1 COPYRIGHT
This function fails if called on a QUIC stream SSL object or on a non-QUIC SSL
object.
-SSL_new_stream() may also fail if the connection that the stream is being
-allocated in relation to has reached the maximum number of streams allowed by
-the connection (as dictated by the B<max_streams_bidi> or B<max_streams_uni>
-transport parameter values negotiated by the connection with the server). In
-this event the NULL return will be accompanied by an error on the error stack
-(obtainable via ERR_get_error()), which will contain a reason code of
+SSL_new_stream() may also fail if the underlying connection has reached the
+maximum stream count, based on the B<max_streams_bidi> or B<max_streams_uni>
+transport parameter values negotiated with the peer. In this event the NULL
+return will be accompanied by an error on the error stack (obtainable via
+ERR_get_error()), which will contain a reason code of
B<SSL_R_STREAM_COUNT_LIMITED>. When this error is encountered, the operation
may be retried. It is recommended that, prior to retry, the error stack be
cleared via a call to ERR_clear_error(), and that the TLS state machine be
-triggered via a call to SSL_handle_events() to process any potential updates
+activated via a call to SSL_handle_events() to process any potential updates
from the server allowing additional streams to be created.
=head1 SEE ALSO
projects / thirdparty / openssl.git / commitdiff
