From: Neil Horman <nhorman@openssl.org>
Date: Mon, 20 Oct 2025 15:52:44 +0000 (-0400)
Subject: Add docs for OSSL_QUIC_method() and SSL_listen_ex()
X-Git-Tag: 4.0-PRE-CLANG-FORMAT-WEBKIT~7
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c2b14acee4b7d6d1b20ee5af664d51193ec32f76;p=thirdparty%2Fopenssl.git

Add docs for OSSL_QUIC_method() and SSL_listen_ex()

Reviewed-by: Saša Nedvědický <sashan@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/27397)
---

diff --git a/doc/man3/OSSL_QUIC_client_method.pod b/doc/man3/OSSL_QUIC_client_method.pod
index 564425167af..2c1ef920d8a 100644
--- a/doc/man3/OSSL_QUIC_client_method.pod
+++ b/doc/man3/OSSL_QUIC_client_method.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method, OSSL_QUIC_server_method
+OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method, OSSL_QUIC_server_method, OSSL_QUIC_method
 - Provide SSL_METHOD objects for QUIC enabled functions
 
 =head1 SYNOPSIS
@@ -12,6 +12,7 @@ OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method, OSSL_QUIC_server_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);
+ const SSL_METHOD *OSSL_QUIC_method(void);
 
 =head1 DESCRIPTION
 
@@ -30,13 +31,19 @@ The OSSL_QUIC_server_method() provides server-side QUIC protocol support and
 must be used with the L<SSL_new_listener(3)> API. Attempting to use
 OSSL_QUIC_server_method() with L<SSL_new(3)> will result in an error.
 
+The OSSL_QUIC_method() provides generic QUIC protocol support when a user wishes to
+defer selection of server or client protocol functionality until such time as a
+connection is made.  This is similar to the functionality provided by
+L<DTLS_method(3)>, and can be used with the SSL_listen_ex() call, which behaves
+similarly to L<DTLSv1_listen(3)>.
+
 =head1 RETURN VALUES
 
 These functions return pointers to the constant method objects.
 
 =head1 SEE ALSO
 
-L<SSL_CTX_new_ex(3)>, L<SSL_new_listener(3)>
+L<SSL_CTX_new_ex(3)>, L<SSL_new_listener(3)>, L<SSL_listen_ex(3)>
 
 =head1 HISTORY
 
@@ -45,6 +52,8 @@ OpenSSL 3.2.
 
 OSSL_QUIC_server_method() was added in OpenSSL 3.5.
 
+OSSL_QUIC_method() was added in OpenSSL 4.0.
+
 =head1 COPYRIGHT
 
 Copyright 2022-2025 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/SSL_new_listener.pod b/doc/man3/SSL_new_listener.pod
index 291c103381e..3c17347becb 100644
--- a/doc/man3/SSL_new_listener.pod
+++ b/doc/man3/SSL_new_listener.pod
@@ -3,7 +3,7 @@
 =head1 NAME
 
 SSL_new_listener, SSL_new_listener_from, SSL_is_listener, SSL_get0_listener,
-SSL_listen,
+SSL_listen, SSL_listen_ex,
 SSL_accept_connection, SSL_get_accept_connection_queue_len,
 SSL_new_from_listener,
 SSL_ACCEPT_CONNECTION_NO_BLOCK - SSL object interface for abstracted connection
@@ -20,6 +20,7 @@ acceptance
  SSL *SSL_get0_listener(SSL *ssl);
 
  int SSL_listen(SSL *ssl);
+ int SSL_listen_ex(SSL *ssl, SSL *new_conn);
 
  #define SSL_ACCEPT_CONNECTION_NO_BLOCK
  SSL *SSL_accept_connection(SSL *ssl, uint64_t flags);
@@ -124,6 +125,22 @@ 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_listen_ex() function behaves in a similar fashion to L<DTLSv1_listen(3)>
+in that it polls a listening SSL object, and, if a new connection is available,
+writes that connection into the SSL object pointed to by B<new_conn>.  Note that
+once a connection is returned from a listener via this call, accepting
+connections via L<SSL_accept_connection(3)> is no longer permissible, and will
+result in an error.  Note that many calls into the QUIC api may trigger the quic reactor
+(such as L<SSL_poll(3)>), and will set the port into a mode in which L<SSL_accept_connection(3)>
+is assumed.  To avoid this, it is recommended that, if the use of SSL_listen_ex use is desired, that
+it is the first I/O call made to the SSL object to which the port is attached.
+
+Likewise, if a listener has accepted a connection via
+L<SSL_accept_connection(3)>, it is impermissible to accept connections via
+B<SSL_listen_ex()>.  Note also that SSL objects passed in the B<new_conn>
+parameter to B<SSL_listen_ex()> must be created using L<OSSL_QUIC_method(3)> or
+L<OSSL_QUIC_server_method(3)>.
+
 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
@@ -198,6 +215,11 @@ object on which it is called) or NULL.
 
 SSL_listen() returns 1 on success or 0 on failure.
 
+SSL_listen_ex() returns 1 when a new connection was accepted on the new_conn
+parameter, 0 if no new connection was available at the time of the call, or -1
+in the event an internal error occurred, signaling a need to check the error
+queue.
+
 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.
 
@@ -228,6 +250,8 @@ L<SSL_set_blocking_mode(3)>
 
 These functions were added in OpenSSL 3.5.
 
+SSL_listen_ex() was added in OpenSSL 4.0
+
 =head1 COPYRIGHT
 
 Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved.