--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_new_listener, SSL_is_listener, SSL_get0_listener, SSL_listen,
+SSL_accept_connection, SSL_get_accept_connection_queue_len,
+SSL_new_from_listener, SSL_LISTENER_FLAG_NO_ACCEPT,
+SSL_ACCEPT_CONNECTION_NO_BLOCK - SSL object interface for abstracted connection
+acceptance
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ #define SSL_LISTENER_FLAG_NO_ACCEPT
+ SSL *SSL_new_listener(SSL_CTX *ctx, 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);
+
+=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
+expressly documented as being supported on a listener SSL object are available.
+
+A listener SSL object supports the following operations:
+
+=over 4
+
+=item
+
+Standard reference counting and free operations, such as L<SSL_up_ref(3)> and
+L<SSL_free(3)>;
+
+=item
+
+Network BIO configuration operations, such as L<SSL_set_bio(3)>;
+
+=item
+
+Event processing and polling enablement APIs such as L<SSL_handle_events(3)>,
+L<SSL_get_event_timeout(3)>, L<SSL_get_rpoll_descriptor(3)>,
+L<SSL_get_wpoll_descriptor(3)>, L<SSL_net_read_desired(3)> and
+L<SSL_net_write_desired(3)>;
+
+=item
+
+Accepting network connections using the functions documented in this manual
+page, such as SSL_accept_connection().
+
+=back
+
+The basic workflow of using a listener object is as follows:
+
+=over 4
+
+=item
+
+Create a new listener object using SSL_new_listener() using a B<SSL_CTX> which
+uses a supported B<SSL_METHOD> (such as L<OSSL_QUIC_server_method(3)>);
+
+=item
+
+Configure appropriate network BIOs using L<SSL_set_bio(3)> on the listener SSL
+object;
+
+=item
+
+Configure the blocking mode using L<SSL_set_blocking_mode(3)>;
+
+=item
+
+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.
+
+=back
+
+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 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.
+
+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,
+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.
+
+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 B<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 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.
+
+Currently, listener SSL objects are only supported for QUIC usage via
+L<OSSL_QUIC_server_method(3)>. 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.
+
+=head1 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 use client-only mode, pass the flag B<SSL_LISTENER_FLAG_NO_ACCEPT> when
+calling SSL_new_listener(). In this mode, SSL_listen() still begins the process
+of handling network resources, but incoming connections are never accepted.
+Calling SSL_accept_connection() is an error and will return NULL. One or more
+outgoing connections under a listener can then be created using the call
+SSL_new_from_listener().
+
+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() in
+conjunction with a listener which does accept incoming connections (i.e., which
+was not created using B<SSL_LISTENER_FLAG_NO_ACCEPT>), 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.
+
+Creating a listener using a B<SSL_CTX> which uses a client-oriented
+B<SSL_METHOD> such as L<OSSL_QUIC_client_method(3)> or
+L<OSSL_QUIC_client_thread_method(3)> automatically implies the
+B<SSL_LISTENER_FLAG_NO_ACCEPT> flag. The B<SSL_LISTENER_FLAG_NO_ACCEPT> flag may
+optionally also be specified in this case but is ignored. This is an alternative
+way of using the listener functionality in client-only mode.
+
+=head1 RETURN VALUES
+
+SSL_new_listener() returns 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_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
+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 SEE ALSO
+
+L<OSSL_QUIC_server_method(3)>, L<SSL_free(3)>, L<SSL_set_bio(3)>,
+L<SSL_handle_events(3)>, L<SSL_get_rpoll_descriptor(3)>,
+L<SSL_set_blocking_mode(3)>
+
+=head1 HISTORY
+
+OSSL_QUIC_client_method() and OSSL_QUIC_client_thread_method() were added in
+OpenSSL 3.2.
+
+OSSL_QUIC_server_method() was added in OpenSSL @VERSION_QUIC_SERVER@.
+
+=head1 COPYRIGHT
+
+Copyright 2022-2024 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
+L<https://www.openssl.org/source/license.html>.
+
+=cut
projects / thirdparty / openssl.git / commitdiff
