QUIC: Documentation updates

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19703)

diff --git a/doc/man3/SSL_get_tick_timeout.pod b/doc/man3/SSL_get_tick_timeout.pod
index 7fe66c9a9526db13b66bce1fa615ae1ee2b32cc4..9c46c0c6c06202e732f9000e296282b915cd9c43 100644 (file)
--- a/doc/man3/SSL_get_tick_timeout.pod
+++ b/doc/man3/SSL_get_tick_timeout.pod
@@ -13,9 +13,7 @@ SSL_get_tick_timeout - determine when an SSL object next needs to be ticked
 =head1 DESCRIPTION
 
 SSL_get_tick_timeout() determines when the SSL object next needs to perform
-internal processing due to the passage of time. It is currently applicable only
-to DTLS and QUIC connection SSL objects, and is not supported on other kinds of
-SSL object.
+internal processing due to the passage of time.
 
 Calling SSL_get_tick_timeout() results in B<*tv> being written with an amount of
 time left before the SSL object needs to be ticked. If the SSL object needs to
@@ -23,6 +21,10 @@ be ticked immediately, it is set to zero; if the SSL object currently does not
 need to be ticked at any point in the future, B<tv_sec> is set to -1,
 representing infinity.
 
+This function is currently applicable only to DTLS and QUIC connection SSL
+objects. If it is called on any other kind of SSL object, it always outputs
+infinity. This is considered a success condition.
+
 Note that the value output by a call to SSL_get_tick_timeout() may change as a
 result of other calls to the SSL object.
 

diff --git a/doc/man3/SSL_set_initial_peer_addr.pod b/doc/man3/SSL_set_initial_peer_addr.pod
index 9190198682fb5350e2f98f50120aa270a2333d5a..0e30e573f449be21ff08975c34683c79df75c0c3 100644 (file)
--- a/doc/man3/SSL_set_initial_peer_addr.pod
+++ b/doc/man3/SSL_set_initial_peer_addr.pod
@@ -18,9 +18,13 @@ can be used only on a QUIC connection SSL object, and can be used only before a
 connection attempt is first made. B<addr> must point to a B<BIO_ADDR>
 representing a UDP destination address of the server to connect to.
 
-In some cases, the initial destination peer address can be detected
-automatically when the SSL object is first provided with a suitable BIO. This
-behaviour can be overridden by calling SSL_set_initial_peer_addr() explicitly.
+Where a QUIC connection object is provided with a write BIO which supports the
+B<BIO_CTRL_DGRAM_GET_PEER> control (for example, B<BIO_s_dgram>), the initial
+destination peer address can be detected automatically; if
+B<BIO_CTRL_DGRAM_GET_PEER> returns a valid (non-B<AF_UNSPEC>) peer address and
+no valid peer address has yet been set, this will be set automatically as the
+initial peer address. This behaviour can be overridden by calling
+SSL_set_initial_peer_addr() with a valid peer address explicitly.
 
 The destination address used by QUIC may change over time in response to
 connection events, such as connection migration (where supported).

diff --git a/doc/man3/SSL_tick.pod b/doc/man3/SSL_tick.pod
index 5aab534dd7ec2c07bb188a55abace1ba42ae8486..f1350bff4728f82e5a9d67635d1b46898d0c7df7 100644 (file)
--- a/doc/man3/SSL_tick.pod
+++ b/doc/man3/SSL_tick.pod
@@ -37,6 +37,11 @@ DTLSv1_handle_timeout(). Since SSL_tick() handles a superset of the use cases of
 DTLSv1_handle_timeout(), it should be preferred for new applications which do
 not require support for OpenSSL 3.1 or older.
 
+When using DTLS, an application must call SSL_tick() as indicated by calls to
+SSL_get_tick_timeout(); ticking is not performed automatically by calls to other
+SSL functions such as SSL_read() or SSL_write(). Note that this is different to
+QUIC which also performs ticking implicitly; see below.
+
 =item QUIC connection SSL objects
 
 Using SSL_tick() on an SSL object which represents a QUIC connection allows
@@ -48,9 +53,9 @@ Ordinarily, when an application uses an SSL object in blocking mode, it does not
 need to call SSL_tick() because OpenSSL performs ticking internally on an
 automatic basis. However, if an application uses a QUIC connection in
 nonblocking mode, it must at a minimum ensure that SSL_tick() is called
-periodically to allow timeout events to be handled. An application can
-find out when it next needs to call SSL_tick() for this purpose (if at all) by
-calling SSL_get_tick_timeout().
+periodically to allow timeout events to be handled. An application can find out
+when it next needs to call SSL_tick() for this purpose (if at all) by calling
+SSL_get_tick_timeout().
 
 Calling SSL_tick() on a QUIC connection SSL object being used in blocking mode
 is not necessary unless no I/O calls (such as SSL_read() or SSL_write()) will be
@@ -66,6 +71,9 @@ TODO(QUIC): Update the above paragraph once we support thread assisted mode.
 
 =back
 
+Calling SSL_tick() on any other kind of SSL object is a no-op. This is
+considered a success case.
+
 =head1 RETURN VALUES
 
 Returns 1 on success and 0 on failure.