QUIC: Add manpage for listener API

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from #23334)

doc/build.info

@@ -2659,6 +2659,10 @@ DEPEND[html/man3/SSL_new.html]=man3/SSL_new.pod
 GENERATE[html/man3/SSL_new.html]=man3/SSL_new.pod
 DEPEND[man/man3/SSL_new.3]=man3/SSL_new.pod
 GENERATE[man/man3/SSL_new.3]=man3/SSL_new.pod
+DEPEND[html/man3/SSL_new_listener.html]=man3/SSL_new_listener.pod
+GENERATE[html/man3/SSL_new_listener.html]=man3/SSL_new_listener.pod
+DEPEND[man/man3/SSL_new_listener.3]=man3/SSL_new_listener.pod
+GENERATE[man/man3/SSL_new_listener.3]=man3/SSL_new_listener.pod
 DEPEND[html/man3/SSL_new_stream.html]=man3/SSL_new_stream.pod
 GENERATE[html/man3/SSL_new_stream.html]=man3/SSL_new_stream.pod
 DEPEND[man/man3/SSL_new_stream.3]=man3/SSL_new_stream.pod
@@ -3596,6 +3600,7 @@ html/man3/SSL_key_update.html \
 html/man3/SSL_library_init.html \
 html/man3/SSL_load_client_CA_file.html \
 html/man3/SSL_new.html \
+html/man3/SSL_new_listener.html \
 html/man3/SSL_new_stream.html \
 html/man3/SSL_pending.html \
 html/man3/SSL_poll.html \
@@ -4241,6 +4246,7 @@ man/man3/SSL_key_update.3 \
 man/man3/SSL_library_init.3 \
 man/man3/SSL_load_client_CA_file.3 \
 man/man3/SSL_new.3 \
+man/man3/SSL_new_listener.3 \
 man/man3/SSL_new_stream.3 \
 man/man3/SSL_pending.3 \
 man/man3/SSL_poll.3 \

doc/man3/OSSL_QUIC_client_method.pod

@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method
+OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method, OSSL_QUIC_server_method
 - Provide SSL_METHOD objects for QUIC enabled functions
 
 =head1 SYNOPSIS
@@ -11,6 +11,7 @@ OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method
 
  const SSL_METHOD *OSSL_QUIC_client_method(void);
  const SSL_METHOD *OSSL_QUIC_client_thread_method(void);
+ const SSL_METHOD *OSSL_QUIC_server_method(void);
 
 =head1 DESCRIPTION
 
@@ -25,22 +26,28 @@ The OSSL_QUIC_client_method() does not use threads and depends on
 nonblocking mode of operation and the application periodically calling SSL
 functions.
 
+The OSSL_QUIC_server_method() provides server-side QUIC protocol support and
+must be used using the L<SSL_new_listener(3)> API. Attempting to use
+OSSL_QUIC_server_method() with L<SSL_new(3)> will result in an error.
+
 =head1 RETURN VALUES
 
 These functions return pointers to the constant method objects.
 
 =head1 SEE ALSO
 
-L<SSL_CTX_new_ex(3)>
+L<SSL_CTX_new_ex(3)>, L<SSL_new_listener(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-2023 The OpenSSL Project Authors. All Rights Reserved.
+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

doc/man3/SSL_new_listener.pod

@@ -0,0 +1,209 @@
+=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

include/openssl/ssl.h.in

@@ -2285,7 +2285,10 @@ __owur int SSL_is_connection(SSL *s);
 
 __owur int SSL_is_listener(SSL *ssl);
 __owur SSL *SSL_get0_listener(SSL *s);
+#define SSL_LISTENER_FLAG_NO_ACCEPT     (1UL << 0)
 __owur SSL *SSL_new_listener(SSL_CTX *ctx, uint64_t flags);
+__owur SSL *SSL_new_from_listener(SSL *ssl, uint64_t flags);
+#define SSL_ACCEPT_CONNECTION_NO_BLOCK  (1UL << 0)
 __owur SSL *SSL_accept_connection(SSL *ssl, uint64_t flags);
 __owur size_t SSL_get_accept_connection_queue_len(SSL *ssl);
 __owur int SSL_listen(SSL *ssl);

util/libssl.num

@@ -590,3 +590,4 @@ SSL_new_listener                        ?	3_3_0	EXIST::FUNCTION:
 SSL_accept_connection                   ?	3_3_0	EXIST::FUNCTION:
 SSL_get_accept_connection_queue_len     ?	3_3_0	EXIST::FUNCTION:
 SSL_listen                              ?	3_3_0	EXIST::FUNCTION:
+SSL_new_from_listener                   ?	3_3_0	EXIST::FUNCTION:

util/other.syms

@@ -734,6 +734,7 @@ SSL_STREAM_STATE_FINISHED               define
 SSL_STREAM_STATE_RESET_LOCAL            define
 SSL_STREAM_STATE_RESET_REMOTE           define
 SSL_STREAM_STATE_CONN_CLOSED            define
+SSL_ACCEPT_CONNECTION_NO_BLOCK          define
 SSL_ACCEPT_STREAM_NO_BLOCK              define
 SSL_DEFAULT_STREAM_MODE_AUTO_BIDI       define
 SSL_DEFAULT_STREAM_MODE_AUTO_UNI        define
@@ -758,6 +759,8 @@ SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT  define
 SSL_VALUE_STREAM_WRITE_BUF_SIZE         define
 SSL_VALUE_STREAM_WRITE_BUF_USED         define
 SSL_VALUE_STREAM_WRITE_BUF_AVAIL        define
+SSL_WRITE_FLAG_CONCLUDE                 define
+SSL_LISTENER_FLAG_NO_ACCEPT             define
 TLS_DEFAULT_CIPHERSUITES                define deprecated 3.0.0
 X509_CRL_http_nbio                      define deprecated 3.0.0
 X509_http_nbio                          define deprecated 3.0.0