From: Hugo Landau Date: Wed, 30 Nov 2022 08:04:34 +0000 (+0000) Subject: QUIC: Documentation updates X-Git-Tag: openssl-3.2.0-alpha1~1476 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2fff884c86a7a0497c10a73da74b006d5e6e9039;p=thirdparty%2Fopenssl.git QUIC: Documentation updates Reviewed-by: Tomas Mraz Reviewed-by: Matt Caswell (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 7fe66c9a952..9c46c0c6c06 100644 --- 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 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 9190198682f..0e30e573f44 100644 --- 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 must point to a B 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 control (for example, B), the initial +destination peer address can be detected automatically; if +B returns a valid (non-B) 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 5aab534dd7e..f1350bff472 100644 --- 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.