QUIC CSM: Documentation for new APIs

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

8 files changed, 525 insertions, 5 deletions

diff --git a/doc/build.info b/doc/build.info
index c1d6a5f1dc..2b169f1cf2 100644
--- a/doc/build.info
+++ b/doc/build.info
@@ -607,6 +607,10 @@ DEPEND[html/man3/BIO_get_ex_new_index.html]=man3/BIO_get_ex_new_index.pod
 GENERATE[html/man3/BIO_get_ex_new_index.html]=man3/BIO_get_ex_new_index.pod
 DEPEND[man/man3/BIO_get_ex_new_index.3]=man3/BIO_get_ex_new_index.pod
 GENERATE[man/man3/BIO_get_ex_new_index.3]=man3/BIO_get_ex_new_index.pod
+DEPEND[html/man3/BIO_get_rpoll_descriptor.html]=man3/BIO_get_rpoll_descriptor.pod
+GENERATE[html/man3/BIO_get_rpoll_descriptor.html]=man3/BIO_get_rpoll_descriptor.pod
+DEPEND[man/man3/BIO_get_rpoll_descriptor.3]=man3/BIO_get_rpoll_descriptor.pod
+GENERATE[man/man3/BIO_get_rpoll_descriptor.3]=man3/BIO_get_rpoll_descriptor.pod
 DEPEND[html/man3/BIO_meth_new.html]=man3/BIO_meth_new.pod
 GENERATE[html/man3/BIO_meth_new.html]=man3/BIO_meth_new.pod
 DEPEND[man/man3/BIO_meth_new.3]=man3/BIO_meth_new.pod
@@ -2539,6 +2543,10 @@ DEPEND[html/man3/SSL_get_rbio.html]=man3/SSL_get_rbio.pod
 GENERATE[html/man3/SSL_get_rbio.html]=man3/SSL_get_rbio.pod
 DEPEND[man/man3/SSL_get_rbio.3]=man3/SSL_get_rbio.pod
 GENERATE[man/man3/SSL_get_rbio.3]=man3/SSL_get_rbio.pod
+DEPEND[html/man3/SSL_get_rpoll_descriptor.html]=man3/SSL_get_rpoll_descriptor.pod
+GENERATE[html/man3/SSL_get_rpoll_descriptor.html]=man3/SSL_get_rpoll_descriptor.pod
+DEPEND[man/man3/SSL_get_rpoll_descriptor.3]=man3/SSL_get_rpoll_descriptor.pod
+GENERATE[man/man3/SSL_get_rpoll_descriptor.3]=man3/SSL_get_rpoll_descriptor.pod
 DEPEND[html/man3/SSL_get_session.html]=man3/SSL_get_session.pod
 GENERATE[html/man3/SSL_get_session.html]=man3/SSL_get_session.pod
 DEPEND[man/man3/SSL_get_session.3]=man3/SSL_get_session.pod
@@ -2547,6 +2555,10 @@ DEPEND[html/man3/SSL_get_shared_sigalgs.html]=man3/SSL_get_shared_sigalgs.pod
 GENERATE[html/man3/SSL_get_shared_sigalgs.html]=man3/SSL_get_shared_sigalgs.pod
 DEPEND[man/man3/SSL_get_shared_sigalgs.3]=man3/SSL_get_shared_sigalgs.pod
 GENERATE[man/man3/SSL_get_shared_sigalgs.3]=man3/SSL_get_shared_sigalgs.pod
+DEPEND[html/man3/SSL_get_tick_timeout.html]=man3/SSL_get_tick_timeout.pod
+GENERATE[html/man3/SSL_get_tick_timeout.html]=man3/SSL_get_tick_timeout.pod
+DEPEND[man/man3/SSL_get_tick_timeout.3]=man3/SSL_get_tick_timeout.pod
+GENERATE[man/man3/SSL_get_tick_timeout.3]=man3/SSL_get_tick_timeout.pod
 DEPEND[html/man3/SSL_get_verify_result.html]=man3/SSL_get_verify_result.pod
 GENERATE[html/man3/SSL_get_verify_result.html]=man3/SSL_get_verify_result.pod
 DEPEND[man/man3/SSL_get_verify_result.3]=man3/SSL_get_verify_result.pod
@@ -2611,6 +2623,10 @@ DEPEND[html/man3/SSL_set_bio.html]=man3/SSL_set_bio.pod
 GENERATE[html/man3/SSL_set_bio.html]=man3/SSL_set_bio.pod
 DEPEND[man/man3/SSL_set_bio.3]=man3/SSL_set_bio.pod
 GENERATE[man/man3/SSL_set_bio.3]=man3/SSL_set_bio.pod
+DEPEND[html/man3/SSL_set_blocking_mode.html]=man3/SSL_set_blocking_mode.pod
+GENERATE[html/man3/SSL_set_blocking_mode.html]=man3/SSL_set_blocking_mode.pod
+DEPEND[man/man3/SSL_set_blocking_mode.3]=man3/SSL_set_blocking_mode.pod
+GENERATE[man/man3/SSL_set_blocking_mode.3]=man3/SSL_set_blocking_mode.pod
 DEPEND[html/man3/SSL_set_connect_state.html]=man3/SSL_set_connect_state.pod
 GENERATE[html/man3/SSL_set_connect_state.html]=man3/SSL_set_connect_state.pod
 DEPEND[man/man3/SSL_set_connect_state.3]=man3/SSL_set_connect_state.pod
@@ -2619,6 +2635,10 @@ DEPEND[html/man3/SSL_set_fd.html]=man3/SSL_set_fd.pod
 GENERATE[html/man3/SSL_set_fd.html]=man3/SSL_set_fd.pod
 DEPEND[man/man3/SSL_set_fd.3]=man3/SSL_set_fd.pod
 GENERATE[man/man3/SSL_set_fd.3]=man3/SSL_set_fd.pod
+DEPEND[html/man3/SSL_set_initial_peer_addr.html]=man3/SSL_set_initial_peer_addr.pod
+GENERATE[html/man3/SSL_set_initial_peer_addr.html]=man3/SSL_set_initial_peer_addr.pod
+DEPEND[man/man3/SSL_set_initial_peer_addr.3]=man3/SSL_set_initial_peer_addr.pod
+GENERATE[man/man3/SSL_set_initial_peer_addr.3]=man3/SSL_set_initial_peer_addr.pod
 DEPEND[html/man3/SSL_set_retry_verify.html]=man3/SSL_set_retry_verify.pod
 GENERATE[html/man3/SSL_set_retry_verify.html]=man3/SSL_set_retry_verify.pod
 DEPEND[man/man3/SSL_set_retry_verify.3]=man3/SSL_set_retry_verify.pod
@@ -2643,6 +2663,10 @@ DEPEND[html/man3/SSL_state_string.html]=man3/SSL_state_string.pod
 GENERATE[html/man3/SSL_state_string.html]=man3/SSL_state_string.pod
 DEPEND[man/man3/SSL_state_string.3]=man3/SSL_state_string.pod
 GENERATE[man/man3/SSL_state_string.3]=man3/SSL_state_string.pod
+DEPEND[html/man3/SSL_tick.html]=man3/SSL_tick.pod
+GENERATE[html/man3/SSL_tick.html]=man3/SSL_tick.pod
+DEPEND[man/man3/SSL_tick.3]=man3/SSL_tick.pod
+GENERATE[man/man3/SSL_tick.3]=man3/SSL_tick.pod
 DEPEND[html/man3/SSL_want.html]=man3/SSL_want.pod
 GENERATE[html/man3/SSL_want.html]=man3/SSL_want.pod
 DEPEND[man/man3/SSL_want.3]=man3/SSL_want.pod
@@ -2959,6 +2983,7 @@ html/man3/BIO_f_ssl.html \
 html/man3/BIO_find_type.html \
 html/man3/BIO_get_data.html \
 html/man3/BIO_get_ex_new_index.html \
+html/man3/BIO_get_rpoll_descriptor.html \
 html/man3/BIO_meth_new.html \
 html/man3/BIO_new.html \
 html/man3/BIO_new_CMS.html \
@@ -3442,8 +3467,10 @@ html/man3/SSL_get_peer_signature_nid.html \
 html/man3/SSL_get_peer_tmp_key.html \
 html/man3/SSL_get_psk_identity.html \
 html/man3/SSL_get_rbio.html \
+html/man3/SSL_get_rpoll_descriptor.html \
 html/man3/SSL_get_session.html \
 html/man3/SSL_get_shared_sigalgs.html \
+html/man3/SSL_get_tick_timeout.html \
 html/man3/SSL_get_verify_result.html \
 html/man3/SSL_get_version.html \
 html/man3/SSL_group_to_name.html \
@@ -3460,14 +3487,17 @@ html/man3/SSL_session_reused.html \
 html/man3/SSL_set1_host.html \
 html/man3/SSL_set_async_callback.html \
 html/man3/SSL_set_bio.html \
+html/man3/SSL_set_blocking_mode.html \
 html/man3/SSL_set_connect_state.html \
 html/man3/SSL_set_fd.html \
+html/man3/SSL_set_initial_peer_addr.html \
 html/man3/SSL_set_retry_verify.html \
 html/man3/SSL_set_session.html \
 html/man3/SSL_set_shutdown.html \
 html/man3/SSL_set_verify_result.html \
 html/man3/SSL_shutdown.html \
 html/man3/SSL_state_string.html \
+html/man3/SSL_tick.html \
 html/man3/SSL_want.html \
 html/man3/SSL_write.html \
 html/man3/TS_RESP_CTX_new.html \
@@ -3573,6 +3603,7 @@ man/man3/BIO_f_ssl.3 \
 man/man3/BIO_find_type.3 \
 man/man3/BIO_get_data.3 \
 man/man3/BIO_get_ex_new_index.3 \
+man/man3/BIO_get_rpoll_descriptor.3 \
 man/man3/BIO_meth_new.3 \
 man/man3/BIO_new.3 \
 man/man3/BIO_new_CMS.3 \
@@ -4056,8 +4087,10 @@ man/man3/SSL_get_peer_signature_nid.3 \
 man/man3/SSL_get_peer_tmp_key.3 \
 man/man3/SSL_get_psk_identity.3 \
 man/man3/SSL_get_rbio.3 \
+man/man3/SSL_get_rpoll_descriptor.3 \
 man/man3/SSL_get_session.3 \
 man/man3/SSL_get_shared_sigalgs.3 \
+man/man3/SSL_get_tick_timeout.3 \
 man/man3/SSL_get_verify_result.3 \
 man/man3/SSL_get_version.3 \
 man/man3/SSL_group_to_name.3 \
@@ -4074,14 +4107,17 @@ man/man3/SSL_session_reused.3 \
 man/man3/SSL_set1_host.3 \
 man/man3/SSL_set_async_callback.3 \
 man/man3/SSL_set_bio.3 \
+man/man3/SSL_set_blocking_mode.3 \
 man/man3/SSL_set_connect_state.3 \
 man/man3/SSL_set_fd.3 \
+man/man3/SSL_set_initial_peer_addr.3 \
 man/man3/SSL_set_retry_verify.3 \
 man/man3/SSL_set_session.3 \
 man/man3/SSL_set_shutdown.3 \
 man/man3/SSL_set_verify_result.3 \
 man/man3/SSL_shutdown.3 \
 man/man3/SSL_state_string.3 \
+man/man3/SSL_tick.3 \
 man/man3/SSL_want.3 \
 man/man3/SSL_write.3 \
 man/man3/TS_RESP_CTX_new.3 \
diff --git a/doc/man3/BIO_get_rpoll_descriptor.pod b/doc/man3/BIO_get_rpoll_descriptor.pod
new file mode 100644
index 0000000000..652837d924
--- /dev/null
+++ b/doc/man3/BIO_get_rpoll_descriptor.pod
@@ -0,0 +1,116 @@
+=pod
+
+=head1 NAME
+
+BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor - obtain a structure which
+can be used to determine when a BIO object can next be read or written
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ typedef struct bio_poll_descriptor_st {
+     int type;
+     union {
+         int     fd;
+         union {
+             void        *ptr;
+             uint64_t    u64;
+         } custom[BIO_POLL_DESCRIPTOR_NUM_CUSTOM];
+     } value;
+ } BIO_POLL_DESCRIPTOR;
+
+ __owur int BIO_get_rpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
+ __owur int BIO_get_wpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
+
+=head1 DESCRIPTION
+
+BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor(), on success, fill
+B<*desc> with a poll descriptor. A poll descriptor is a tagged union structure
+which represents some kind of OS or non-OS resource which can be used to
+synchronise on I/O availability events.
+
+BIO_get_rpoll_descriptor() outputs a descriptor which can be used to determine
+when the BIO can (potentially) next be read, and BIO_get_wpoll_descriptor()
+outputs a descriptor which can be used to determine when the BIO can
+(potentially) next be written.
+
+It is permissible for BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor()
+to output the same descriptor.
+
+Poll descriptors can represent different kinds of information. A typical kind of
+resource which might be represented by a poll descriptor is an OS file
+descriptor which can be used with APIs such as select().
+
+The kinds of poll descriptor defined by OpenSSL are:
+
+=over 4
+
+=item BIO_POLL_DESCRIPTOR_TYPE_NONE
+
+Represents the absence of a valid poll descriptor. It may be used by
+BIO_get_rpoll_descriptor() or BIO_get_wpoll_descriptor() to indicate that the
+BIO is not pollable for readability or writeability respectively.
+
+For this type, no field within the B<value> field of the B<BIO_POLL_DESCRIPTOR>
+is valid.
+
+=item BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD
+
+The poll descriptor represents an OS socket resource. The field B<value.fd>
+in the B<BIO_POLL_DESCRIPTOR> is valid if it is not set to -1.
+
+The resource is whatever kind of handle is used by a given OS to represent
+sockets, which may vary by OS. For example, on Windows, the value is a B<SOCKET>
+for use with the Winsock API. On POSIX-like platforms, it is a file descriptor.
+
+Where a poll descriptor of this type is output by BIO_get_rpoll_descriptor(), it
+should be polled for readability to determine when the BIO might next be able to
+successfully complete a BIO_read() operation; likewise, where a poll descriptor
+of this type is output by BIO_get_wpoll_descriptor(), it should be polled for
+writeability to determine when the BIO might next be able to successfully
+complete a BIO_write() operation.
+
+=item BIO_POLL_DESCRIPTOR_CUSTOM_START
+
+Type values beginning with this value (inclusive) are reserved for application
+allocation for custom poll descriptor types. The field B<value.custom> in the
+B<BIO_POLL_DESCRIPTOR> is an array of length B<BIO_POLL_DESCRIPTOR_NUM_CUSTOM>.
+Each entry in this array can store a void pointer or a B<uint64_t> and can be
+used by the application arbitrarily.
+
+=back
+
+Because poll descriptors are a tagged union structure, they can represent
+different kinds of information. New types of poll descriptor may be defined,
+including by applications, according to their needs.
+
+=head1 RETURN VALUES
+
+The functions BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() return 1
+on success and 0 on failure.
+
+These functions are permitted to succeed and initialise B<*desc> with a poll
+descriptor of type B<BIO_POLL_DESCRIPTOR_TYPE_NONE> to indicate that the BIO is
+not pollable for readability or writeability respectively.
+
+=head1 SEE ALSO
+
+L<SSL_tick(3)>, L<SSL_get_tick_timeout(3)>, L<SSL_get_rpoll_descriptor(3)>,
+L<SSL_get_wpoll_descriptor(3)>, L<bio(7)>
+
+=head1 HISTORY
+
+The SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() functions were
+added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2022 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
diff --git a/doc/man3/SSL_get_error.pod b/doc/man3/SSL_get_error.pod
index a90b22d984..efc4e60de2 100644
--- a/doc/man3/SSL_get_error.pod
+++ b/doc/man3/SSL_get_error.pod
@@ -60,8 +60,8 @@ is set. See L<SSL_CTX_set_options(3)> for more details.
 
 The operation did not complete and can be retried later.
 
-B<SSL_ERROR_WANT_READ> is returned when the last operation was a read
-operation from a nonblocking B<BIO>.
+For non-QUIC SSL objects, B<SSL_ERROR_WANT_READ> is returned when the last
+operation was a read operation from a nonblocking B<BIO>.
 It means that not enough data was available at this time to complete the
 operation.
 If at a later time the underlying B<BIO> has data available for reading the same
@@ -72,9 +72,10 @@ still unprocessed data available at either the B<SSL> or the B<BIO> layer, even
 for a blocking B<BIO>.
 See L<SSL_read(3)> for more information.
 
-B<SSL_ERROR_WANT_WRITE> is returned when the last operation was a write
-to a nonblocking B<BIO> and it was unable to sent all data to the B<BIO>.
-When the B<BIO> is writable again, the same function can be called again.
+For non-QUIC SSL objects, B<SSL_ERROR_WANT_WRITE> is returned when the last
+operation was a write to a nonblocking B<BIO> and it was unable to sent all data
+to the B<BIO>. When the B<BIO> is writable again, the same function can be
+called again.
 
 Note that the retry may again lead to an B<SSL_ERROR_WANT_READ> or
 B<SSL_ERROR_WANT_WRITE> condition.
@@ -82,6 +83,15 @@ There is no fixed upper limit for the number of iterations that
 may be necessary until progress becomes visible at application
 protocol level.
 
+For QUIC SSL objects, the meaning of B<SSL_ERROR_WANT_READ> and
+B<SSL_ERROR_WANT_WRITE> have different but largely compatible semantics. Since
+QUIC implements its own flow control and uses UDP datagrams, backpressure
+conditions in terms of the underlying BIO providing network I/O are not directly
+relevant to the circumstances in which these errors are produced. In particular,
+B<SSL_ERROR_WANT_WRITE> indicates that the internal send buffer for a given QUIC
+stream has been filled. Likewise, B<SSL_ERROR_WANT_READ> indicates that the
+internal receive buffer for a given QUIC stream is empty.
+
 It is safe to call SSL_read() or SSL_read_ex() when more data is available
 even when the call that set this error was an SSL_write() or SSL_write_ex().
 However, if the call was an SSL_write() or SSL_write_ex(), it should be called
diff --git a/doc/man3/SSL_get_rpoll_descriptor.pod b/doc/man3/SSL_get_rpoll_descriptor.pod
new file mode 100644
index 0000000000..a23fbfe86e
--- /dev/null
+++ b/doc/man3/SSL_get_rpoll_descriptor.pod
@@ -0,0 +1,93 @@
+=pod
+
+=head1 NAME
+
+SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor, SSL_want_net_read,
+SSL_want_net_write - obtain information which can be used to determine when
+network I/O can be performed
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ __owur int SSL_get_rpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
+ __owur int SSL_get_wpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
+ __owur int SSL_want_net_read(SSL *s);
+ __owur int SSL_want_net_write(SSL *s);
+
+=head1 DESCRIPTION
+
+The functions SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() can be
+used to determine when an SSL object which represents a QUIC connection can
+perform useful network I/O, so that an application using a QUIC connection SSL
+object in nonblocking mode can determine when it should call SSL_tick().
+
+On success, these functions output poll descriptors. For more information on
+poll descriptors, see L<BIO_get_rpoll_descriptor(3)>.
+
+The functions SSL_want_net_read() and SSL_want_net_write() return 1 or 0
+depending on whether the SSL object is currently interested in receiving data
+from the network and/or writing data to the network respectively.
+If an SSL object is not interested in reading data from the network at the
+current time, SSL_want_net_read() will return 0; likewise, if an SSL object is
+not interested in writing data to the network at the current time,
+SSL_want_net_write() will return 0.
+
+The intention is that an application using QUIC in nonblocking mode can use
+these calls, in conjunction with L<SSL_get_tick_timeout(3)> to wait for network
+I/O conditions which allow the SSL object to perform useful work. When such a
+condition arises, L<SSL_tick(3)> should be called.
+
+In particular, the expected usage is as follows:
+
+=over 4
+
+=item *
+
+SSL_tick() should be called whenever the timeout returned by
+SSL_get_tick_timeout(3) (if any) expires
+
+=item *
+
+If the last call to SSL_want_net_read() returned 1, SSL_tick() should be called
+whenever the poll descriptor output by SSL_get_rpoll_descriptor() becomes
+readable.
+
+=item *
+
+If the last call to SSL_want_net_write() returned 1, SSL_tick() should be called
+whenever the poll descriptor output by SSL_get_wpoll_descriptor() becomes
+writable.
+
+=back
+
+The return values of the SSL_want_net_read() and SSL_want_net_write() functions
+may change in response to any call to the SSL object other than
+SSL_want_net_read(), SSL_want_net_write(), SSL_get_rpoll_descriptor(),
+SSL_get_wpoll_descriptor() and SSL_get_tick_timeout().
+
+These functions are not supported on non-QUIC SSL objects.
+
+=head1 RETURN VALUES
+
+These functions return 1 on success and 0 on failure.
+
+=head1 SEE ALSO
+
+L<SSL_tick(3)>, L<SSL_get_tick_timeout(3)>, L<ssl(7)>
+
+=head1 HISTORY
+
+The SSL_get_rpoll_descriptor(), SSL_get_wpoll_descriptor(), SSL_want_net_read()
+and SSL_want_net_write() functions were added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2022 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
diff --git a/doc/man3/SSL_get_tick_timeout.pod b/doc/man3/SSL_get_tick_timeout.pod
new file mode 100644
index 0000000000..7fe66c9a95
--- /dev/null
+++ b/doc/man3/SSL_get_tick_timeout.pod
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+SSL_get_tick_timeout - determine when an SSL object next needs to be ticked
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ __owur int SSL_get_tick_timeout(SSL *s, struct timeval *tv);
+
+=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.
+
+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
+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.
+
+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.
+
+Once the timeout expires, SSL_tick() should be called to handle any internal
+processing which is due; for more information, see L<SSL_tick(3)>.
+
+=head1 RETURN VALUES
+
+Returns 1 on success and 0 on failure.
+
+=head1 SEE ALSO
+
+L<SSL_tick(3)>, L<ssl(7)>
+
+=head1 HISTORY
+
+The SSL_get_tick_timeout() function was added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2022 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
diff --git a/doc/man3/SSL_set_blocking_mode.pod b/doc/man3/SSL_set_blocking_mode.pod
new file mode 100644
index 0000000000..328e2709bf
--- /dev/null
+++ b/doc/man3/SSL_set_blocking_mode.pod
@@ -0,0 +1,69 @@
+=pod
+
+=head1 NAME
+
+SSL_set_blocking_mode, SSL_get_blocking_mode - configure blocking mode for a
+QUIC SSL object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ __owur int SSL_set_blocking_mode(SSL *s, int blocking);
+ __owur int SSL_get_blocking_mode(SSL *s);
+
+=head1 DESCRIPTION
+
+SSL_set_blocking_mode() can be used to enable or disable blocking mode on a QUIC
+connection SSL object. By default, blocking is enabled, unless the SSL object is
+configured to use an underlying read or write BIO which cannot provide a poll
+descriptor (see L<BIO_get_rpoll_descriptor(3)>), as blocking mode cannot be
+supported in this case.
+
+To enable blocking mode, call SSL_set_blocking_mode() with B<blocking> set to 1;
+to disable it, call SSL_set_blocking_mode() with B<blocking> set to 0.
+
+To retrieve the current blocking mode, call SSL_get_blocking_mode().
+
+Blocking mode means that calls such as SSL_read() and SSL_write() will block
+until the requested operation can be performed. In nonblocking mode, these
+calls will fail if the requested operation cannot be performed immediately; see
+L<SSL_get_error(3)>.
+
+These functions are only applicable to QUIC connection SSL objects. Other kinds
+of SSL object, such as those for TLS, automatically function in blocking or
+nonblocking mode based on whether the underlying network read and write BIOs
+provided to the SSL object are themselves configured in nonblocking mode.
+
+Where a QUIC connection SSL object is used in nonblocking mode, an application
+is responsible for ensuring that the SSL object is ticked regularly; see
+L<SSL_tick(3)>.
+
+=head1 RETURN VALUES
+
+SSL_set_blocking_mode() returns 1 on success and 0 on failure. The function
+fails if called on a SSL object which does not represent a QUIC connection,
+or if blocking mode cannot be used for the given connection.
+
+SSL_get_blocking_mode() returns 1 if blocking is currently enabled. It returns
+-1 if called on an unsupported SSL object.
+
+=head1 SEE ALSO
+
+L<SSL_tick(3)>, L<ssl(7)>
+
+=head1 HISTORY
+
+The SSL_set_blocking_mode() and SSL_get_blocking_mode() functions were added in
+OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2022 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
diff --git a/doc/man3/SSL_set_initial_peer_addr.pod b/doc/man3/SSL_set_initial_peer_addr.pod
new file mode 100644
index 0000000000..9190198682
--- /dev/null
+++ b/doc/man3/SSL_set_initial_peer_addr.pod
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+SSL_set_initial_peer_addr - set the initial peer address for a QUIC connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ __owur int SSL_set_initial_peer_addr(SSL *s, const BIO_ADDR *addr);
+
+=head1 DESCRIPTION
+
+SSL_set_initial_peer_addr() sets the initial destination peer address to be used
+for the purposes of establishing a QUIC connection in client mode. This function
+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.
+
+The destination address used by QUIC may change over time in response to
+connection events, such as connection migration (where supported).
+SSL_set_initial_peer_addr() configures the destination address used for initial
+connection establishment, and does not confer any guarantee about the
+destination address being used for communication at any later time in the
+connection lifecycle.
+
+=head1 RETURN VALUES
+
+Returns 1 on success and 0 on failure.
+
+=head1 SEE ALSO
+
+L<BIO_ADDR(3)>, L<ssl(7)>
+
+=head1 HISTORY
+
+The SSL_set_initial_peer_addr() function was added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2022 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
diff --git a/doc/man3/SSL_tick.pod b/doc/man3/SSL_tick.pod
new file mode 100644
index 0000000000..5aab534dd7
--- /dev/null
+++ b/doc/man3/SSL_tick.pod
@@ -0,0 +1,90 @@
+=pod
+
+=head1 NAME
+
+SSL_tick - advance asynchronous state machine and perform network I/O
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_tick(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_tick() performs any internal processing which is due on a SSL object. The
+exact operations performed by SSL_tick() vary depending on what kind of protocol
+is being used with the given SSL object. For example, SSL_tick() may handle
+timeout events which have become due, or may attempt, to the extent currently
+possible, to perform network I/O operations on one of the BIOs underlying the
+SSL object.
+
+The primary use case for SSL_tick() is to allow an application which uses
+OpenSSL in nonblocking mode to give OpenSSL an opportunity to handle timer
+events, or to respond to the availability of new data to be read from an
+underlying BIO, or to respond to the opportunity to write pending data to an
+underlying BIO.
+
+SSL_tick() can be used only with the following types of SSL object:
+
+=over 4
+
+=item DTLS SSL objects
+
+Using SSL_tick() on an SSL object being used with a DTLS method allows timeout
+events to be handled properly. This is equivalent to a call to
+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.
+
+=item QUIC connection SSL objects
+
+Using SSL_tick() on an SSL object which represents a QUIC connection allows
+timeout events to be handled properly, as well as incoming network data to be
+processed, and queued outgoing network data to be written, if the underlying BIO
+has the capacity to accept it.
+
+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().
+
+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
+made to the object for a substantial period of time. So long as at least one
+call to the SSL object is blocking, no such call is needed. However, SSL_tick()
+may optionally be used on a QUIC connection object if desired.
+
+=begin comment
+
+TODO(QUIC): Update the above paragraph once we support thread assisted mode.
+
+=end comment
+
+=back
+
+=head1 RETURN VALUES
+
+Returns 1 on success and 0 on failure.
+
+=head1 SEE ALSO
+
+L<SSL_get_tick_timeout(3)>, L<ssl(7)>
+
+=head1 HISTORY
+
+The SSL_tick() function was added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2022 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