openssl
/
openssl
mirror of https://github.com/openssl/openssl
1
0
Fork 0
Code Issues Releases Wiki Activity

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)
This commit is contained in:
Hugo Landau 2022-11-30 08:04:34 +00:00
parent ca41f6b7e9
commit 2fff884c86
3 changed files with 23 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/man3/SSL_get_tick_timeout.pod
View File

@ -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.

10
doc/man3/SSL_set_initial_peer_addr.pod
View File

@ -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).

14
doc/man3/SSL_tick.pod
View File

@ -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.