QUIC MSST: Add documentation for new APIs

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

10 files changed, 909 insertions, 0 deletions

diff --git a/doc/man3/SSL_accept_stream.pod b/doc/man3/SSL_accept_stream.pod
new file mode 100644
index 0000000000..55c1868323
--- /dev/null
+++ b/doc/man3/SSL_accept_stream.pod
@@ -0,0 +1,74 @@
+=pod
+
+=head1 NAME
+
+SSL_accept_stream, SSL_get_accept_stream_queue_len, SSL_ACCEPT_STREAM_NO_BLOCK -
+accept an incoming QUIC stream from a QUIC peer
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ #define SSL_ACCEPT_STREAM_NO_BLOCK
+
+ SSL *SSL_accept_stream(SSL *ssl, uint64_t flags);
+
+ size_t SSL_get_accept_stream_queue_len(SSL *ssl);
+
+=head1 DESCRIPTION
+
+The SSL_accept_stream() function attempts to dequeue an incoming stream from the
+given QUIC connection SSL object and returns the newly allocated QUIC stream SSL
+object.
+
+If the queue of incoming streams is empty, this function returns NULL (in
+nonblocking mode) or waits for an incoming stream (in blocking mode). This
+function may still return NULL in blocking mode, for example if the underlying
+connection is terminated.
+
+The caller is responsible for managing the lifetime of the returned QUIC stream
+SSL object. The lifespan of the parent QUIC connection SSL object must exceed
+that of the QUIC stream SSL object; that is, the stream object must be freed
+first, using L<SSL_free(3)>.
+
+This function will block if the QUIC connection SSL object is configured in
+blocking mode (see L<SSL_set_blocking_mode(3)>), but this may be bypassed by
+passing the flag B<SSL_ACCEPT_STREAM_NO_BLOCK> in B<flags>. If this flag is set,
+this function never blocks.
+
+SSL_accept_stream_queue_len() returns the number of incoming streams currently
+waiting in the accept queue. It is intended for informational use only, as this
+number may change between a call to it and a subsequent call to
+SSL_accept_stream(), due to SSL_accept_stream() calls by other threads.
+
+Depending on whether default stream functionality is being used, it may be
+necessary to explicitly configure the incoming stream rejection policy before
+streams can be accepted; see L<SSL_set_incoming_stream_reject_policy(3)>.
+
+=head1 RETURN VALUES
+
+SSL_accept_stream() returns a newly allocated QUIC stream SSL object, or NULL if
+no new incoming streams are available, or if the connection has been terminated.
+
+SSL_get_accept_stream_queue_len() returns the number of incoming streams
+currently waiting in the accept queue.
+
+=head1 SEE ALSO
+
+L<SSL_new_stream(3)>, L<SSL_set_blocking_mode(3)>, L<SSL_free(3)>
+
+=head1 HISTORY
+
+SSL_accept_stream() and SSL_get_accept_stream_queue_len() were added in OpenSSL
+3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2023 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_attach_stream.pod b/doc/man3/SSL_attach_stream.pod
new file mode 100644
index 0000000000..45e40c82e5
--- /dev/null
+++ b/doc/man3/SSL_attach_stream.pod
@@ -0,0 +1,160 @@
+=pod
+
+=head1 NAME
+
+SSL_attach_stream, SSL_detach_stream, SSL_set_default_stream_mode,
+SSL_DEFAULT_STREAM_MODE_NONE, SSL_DEFAULT_STREAM_MODE_AUTO_BIDI,
+SSL_DEFAULT_STREAM_MODE_AUTO_UNI - manage the default stream for a QUIC
+connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_attach_stream(SSL *conn, SSL *stream);
+ SSL *SSL_detach_stream(SSL *conn);
+
+ #define SSL_DEFAULT_STREAM_MODE_NONE
+ #define SSL_DEFAULT_STREAM_MODE_AUTO_BIDI
+ #define SSL_DEFAULT_STREAM_MODE_AUTO_UNI
+
+ int SSL_set_default_stream_mode(SSL *conn, uint32_t mode);
+
+=head1 DESCRIPTION
+
+A QUIC connection SSL object may have a default stream attached to it. A default
+stream is a QUIC stream to which calls to L<SSL_read(3)> and L<SSL_write(3)>
+made on a QUIC connection SSL object are redirected. Default stream handling
+allows legacy applications to use QUIC similarly to a traditional TLS
+connection.
+
+When not disabled, a default stream is automatically created on an outgoing
+connection once L<SSL_read(3)> or L<SSL_write(3)> is called.
+
+A QUIC stream must be explicitly designated as client-initiated or
+server-initiated up front. This broadly corresponds to whether an application
+protocol involves the client transmitting first, or the server transmitting
+first. As such, if L<SSL_read(3)> is called first (before any call to
+L<SSL_write(3)>)  after establishing a connection, OpenSSL will wait for the
+server to open the first server-initiated stream, and then bind this as the
+default stream. Conversely, if L<SSL_write(3)> is called before any call to
+L<SSL_read(3)>, OpenSSL assumes the client wishes to transmit first, creates a
+client-initiated stream, and binds this as the default stream.
+
+By default, the default stream created is bidirectional. If a unidirectional
+stream is desired, or if the application wishes to disable default stream
+functionality, SSL_set_default_stream_mode() (discussed below) can be used to
+accomplish this.
+
+If a default stream is currently bound to a QUIC connection SSL object, it can
+be detached from that QUIC connection SSL object and used explicitly by calling
+SSL_detach_stream(), which detaches the default stream and returns it as an
+explicit QUIC stream SSL object.
+
+Once detached, the caller is responsible for managing the lifetime of the QUIC
+stream SSL object and must free it by calling L<SSL_free(3)>. The lifetime of a
+QUIC connection SSL object must exceed that of any subsidiary QUIC stream SSL
+objects; in other words, QUIC stream SSL objects must be freed before the parent
+QUIC connection SSL object is freed.
+
+When a QUIC connection SSL object has no default stream currently associated
+with it, for example because the default stream was detached or because default
+stream functionality was disabled, calls to functions which require a stream on
+the QUIC connection SSL object will fail.
+
+The act of detaching a stream from a QUIC connection SSL object can be reversed
+by calling SSL_attach_stream(). This can also be used to designate a stream
+obtained via L<SSL_new_stream(3)> or L<SSL_accept_stream(3)> as the default
+stream. SSL_attach_stream() cannot be used if there is already a default stream
+associated with the QUIC connection SSL object; therefore, you may need to call
+SSL_detach_stream() first.
+
+It is recommended that new applications and applications which rely on multiple
+streams forego use of the default stream functionality, which is intended for
+legacy applications.
+
+SSL_set_default_stream_mode() can be used to configure or disable default stream
+handling. It can only be called on a QUIC connection SSL object prior to any
+default stream being created. If used, it is recommended to call it immediately
+after calling L<SSL_new(3)>, prior to initiating a connection. The argument
+B<mode> may be one of the following options:
+
+=over 4
+
+=item SSL_DEFAULT_STREAM_MODE_AUTO_BIDI
+
+This is the default setting. If L<SSL_write(3)> is called prior to any call to
+L<SSL_read(3)>, a bidirectional client-initiated stream is created and bound as
+the default stream. If L<SSL_read(3)> is called prior to any call to
+L<SSL_write(3)>, OpenSSL waits for an incoming stream from the peer (causing
+L<SSL_read(3)> to block if the connection is in blocking mode), and then binds
+that stream as the default stream. Note that this incoming stream may be either
+bidirectional or unidirectional; thus, this setting does not guarantee presence
+of a bidirectional stream when L<SSL_read(3)> is called first. To determine the
+type of a stream after a call to L<SSL_read(3)>, use L<SSL_get_stream_type(3)>.
+
+=item SSL_DEFAULT_STREAM_MODE_AUTO_UNI
+
+In this mode, if L<SSL_write(3)> is called prior to any call to L<SSL_read(3)>,
+a unidirectional client-initiated stream is created and bound as the default
+stream. The behaviour is otherwise identical to that of
+B<SSL_DEFAULT_STREAM_MODE_AUTO_BIDI>. The behaviour when L<SSL_read(3)> is
+called prior to any call to L<SSL_write(3)> is unchanged.
+
+=item SSL_DEFAULT_STREAM_MODE_NONE
+
+Default stream creation is inhibited. This is the recommended mode of operation.
+L<SSL_read(3)> and L<SSL_write(3)> calls cannot be made on the QUIC connection
+SSL object directly. You must obtain streams using L<SSL_new_stream(3)> or
+L<SSL_accept_stream(3)> in order to communicate with the peer.
+
+It is still possible to explicitly attach a stream as the default stream using
+SSL_attach_stream().
+
+=back
+
+A default stream will not be automatically created on a QUIC connection SSL
+object if the default stream mode is set to B<SSL_DEFAULT_STREAM_MODE_NONE>, or
+if the QUIC connection SSL object previously had a default stream which was
+detached using SSL_detach_stream().
+
+L<SSL_set_incoming_stream_reject_policy(3)> interacts significantly with the
+default stream functionality.
+
+=head1 RETURN VALUES
+
+SSL_detach_stream() returns a QUIC stream SSL object, or NULL if there is no
+default stream currently attached.
+
+SSL_attach_stream() returns 1 on success and 0 on failure.
+
+SSL_attach_stream() fails if a default stream is already attached to the QUIC
+connection SSL object.
+
+SSL_set_default_stream_mode() returns 1 on success and 0 on failure.
+
+SSL_set_default_stream_mode() fails if it is called after a default stream has
+already been established.
+
+These functions fail if called on a QUIC stream SSL object or on a non-QUIC SSL
+object.
+
+=head1 SEE ALSO
+
+L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>, L<SSL_free(3)>,
+L<SSL_set_incoming_stream_reject_policy(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2023 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_get0_connection.pod b/doc/man3/SSL_get0_connection.pod
new file mode 100644
index 0000000000..b6c21ad344
--- /dev/null
+++ b/doc/man3/SSL_get0_connection.pod
@@ -0,0 +1,54 @@
+=pod
+
+=head1 NAME
+
+SSL_get0_connection, SSL_is_connection - get a QUIC connection SSL object from a
+QUIC stream SSL object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL *SSL_get0_connection(SSL *ssl);
+ int SSL_is_connection(SSL *ssl);
+
+=head1 DESCRIPTION
+
+The SSL_get0_connection() function, when called on a QUIC stream SSL object,
+returns the QUIC connection SSL object which the QUIC stream SSL object belongs
+to.
+
+When called on a QUIC connection SSL object, it returns the same object.
+
+When called on a non-QUIC object, it returns the same object it was passed.
+
+SSL_is_connection() returns 1 for QUIC connection SSL objects and for non-QUIC
+SSL objects, but returns 0 for QUIC stream SSL objects.
+
+=head1 RETURN VALUES
+
+SSL_get0_connection() returns the QUIC connection SSL object (for a QUIC stream
+SSL object) and otherwise returns the same SSL object passed. It always returns
+non-NULL.
+
+SSL_is_connection() returns 1 if the SSL object is not a QUIC stream SSL object
+and 0 otherwise.
+
+=head1 SEE ALSO
+
+L<SSL_new(3)>, L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2023 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_conn_close_info.pod b/doc/man3/SSL_get_conn_close_info.pod
new file mode 100644
index 0000000000..5f9a2c3e38
--- /dev/null
+++ b/doc/man3/SSL_get_conn_close_info.pod
@@ -0,0 +1,93 @@
+=pod
+
+=head1 NAME
+
+SSL_get_conn_close_info - get information about why a QUIC connection was closed
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ typedef struct ssl_conn_close_info_st {
+     uint64_t error_code;
+     char     *reason;
+     size_t   reason_len;
+     char     is_local;
+     char     is_transport;
+ } SSL_CONN_CLOSE_INFO;
+
+ int SSL_get_conn_close_info(SSL *ssl, SSL_CONN_CLOSE_INFO *info,
+                             size_t info_len);
+
+=head1 DESCRIPTION
+
+The SSL_get_conn_close_info() function provides information about why and how a
+QUIC connection was closed.
+
+Connection closure information is written to B<*info>, which must be non-NULL.
+B<info_len> must be set to B<sizeof(*info)>.
+
+The following fields are set:
+
+=over 4
+
+=item B<error_code>
+
+This is a 62-bit QUIC error code. It is either a 62-bit application error code
+(if B<is_transport> is 0) or a  62-bit standard QUIC transport error code (if
+B<is_transport> is 1).
+
+=item B<reason>
+
+If non-NULL, this is intended to be a UTF-8 textual string briefly describing
+the reason for connection closure. The length of the reason string in bytes is
+given in B<reason_len>. While, if non-NULL, OpenSSL guarantees that this string
+will be zero terminated, consider that this buffer may originate from the
+(untrusted) peer and thus may also contain zero bytes elsewhere. Therefore, use
+of B<reason_len> is recommended.
+
+While it is intended as per the QUIC protocol that this be a UTF-8 string, there
+is no guarantee that this is the case for strings received from the peer.
+
+=item B<is_local>
+
+If 1, connection closure was locally triggered. This could be due to an
+application request (e.g. if B<is_transport> is 0), or (if B<is_transport> is 1)
+due to logic internal to the QUIC implementation (for example, if the peer
+engages in a protocol violation, or an idle timeout occurs).
+
+If 0, connection closure was remotely triggered.
+
+=item B<is_transport>
+
+If 1, connection closure was triggered for QUIC protocol reasons.
+
+If 0, connection closure was triggered by the local or remote application.
+
+=back
+
+=head1 RETURN VALUES
+
+SSL_get_conn_close_info() returns 1 on success and 0 on failure. This function
+fails if called on a QUIC connection SSL object which has not yet been
+terminated. It also fails if called on a QUIC stream SSL object or a non-QUIC
+SSL object.
+
+=head1 SEE ALSO
+
+L<SSL_shutdown_ex(3)>
+
+=head1 HISTORY
+
+This function was added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2023 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_stream_id.pod b/doc/man3/SSL_get_stream_id.pod
new file mode 100644
index 0000000000..b3ac31e3b2
--- /dev/null
+++ b/doc/man3/SSL_get_stream_id.pod
@@ -0,0 +1,98 @@
+=pod
+
+=head1 NAME
+
+SSL_get_stream_id, SSL_get_stream_type, SSL_STREAM_TYPE_NONE,
+SSL_STREAM_TYPE_READ, SSL_STREAM_TYPE_WRITE, SSL_STREAM_TYPE_BIDI - get QUIC
+stream ID and stream type information
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ uint64_t SSL_get_stream_id(SSL *ssl);
+
+ #define SSL_STREAM_TYPE_NONE
+ #define SSL_STREAM_TYPE_BIDI
+ #define SSL_STREAM_TYPE_READ
+ #define SSL_STREAM_TYPE_WRITE
+ int SSL_get_stream_type(SSL *ssl);
+
+=head1 DESCRIPTION
+
+The SSL_get_stream_id() function returns the QUIC stream ID for a QUIC stream
+SSL object, or for a QUIC connection SSL object which has a default stream
+attached.
+
+The SSL_get_stream_type() function identifies what operations can be performed
+on the stream, and returns one of the following values:
+
+=over 4
+
+=item B<SSL_STREAM_TYPE_NONE>
+
+The SSL object is a non-QUIC SSL object, or is a QUIC connection SSL object
+without a default stream attached (see L<SSL_attach_stream(3)>).
+
+=item B<SSL_STREAM_TYPE_BIDI>
+
+The SSL object is a QUIC stream object (or QUIC connection SSL object with a
+default stream attached), and that stream is a bidirectional QUIC stream.
+
+=item B<SSL_STREAM_TYPE_READ>
+
+The SSL object is a QUIC stream object (or QUIC connection SSL object with a
+default stream attached), and that stream is a unidirectional QUIC stream which
+was initiated by the remote peer; thus, it can be read from, but not written to.
+
+=item B<SSL_STREAM_TYPE_WRITE>
+
+The SSL object is a QUIC stream object (or QUIC connection SSL object with a
+default stream attached), and that stream is a unidirectional QUIC stream which
+was initiated by the local application; thus, it can be written to, but not read
+from.
+
+=back
+
+=head1 NOTES
+
+While QUICv1 assigns specific meaning to the low two bits of a QUIC stream ID,
+QUIC stream IDs in future versions of QUIC are not required to have the same
+semantics. Do not determine stream properties using these bits. Instead, use
+SSL_get_stream_type() to determine the stream type.
+
+The SSL_get_stream_type() identifies the type of a QUIC stream based on its
+identity, and does not indicate whether an operation can currently be
+successfully performed on a stream. For example, you might locally initiate a
+unidirectional stream, write to it, and then conclude the stream using
+L<SSL_stream_conclude(3)>, meaning that it can no longer be written to, but
+SSL_get_stream_type() would still return B<SSL_STREAM_TYPE_WRITE>. The value
+returned by SSL_get_stream_type() does not vary over the lifespan of a stream.
+
+=head1 RETURN VALUES
+
+SSL_get_stream_id() returns a QUIC stream ID, or B<UINT64_MAX> if called on an
+SSL object which is not a QUIC SSL object, or if called on a QUIC connection SSL
+object without a default stream attached. Note that valid QUIC stream IDs are
+always below 2**62.
+
+SSL_get_stream_type() returns one of the B<SSL_STREAM_TYPE> values.
+
+=head1 SEE ALSO
+
+L<SSL_attach_stream(3)>, L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2023 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_stream_read_state.pod b/doc/man3/SSL_get_stream_read_state.pod
new file mode 100644
index 0000000000..d04a1ef88a
--- /dev/null
+++ b/doc/man3/SSL_get_stream_read_state.pod
@@ -0,0 +1,162 @@
+=pod
+
+=head1 NAME
+
+SSL_get_stream_read_state, SSL_get_stream_write_state,
+SSL_get_stream_read_error_code, SSL_get_stream_write_error_code,
+SSL_STREAM_STATE_NONE, SSL_STREAM_STATE_OK, SSL_STREAM_STATE_WRONG_DIR,
+SSL_STREAM_STATE_FINISHED, SSL_STREAM_STATE_RESET_LOCAL,
+SSL_STREAM_STATE_RESET_REMOTE, SSL_STREAM_STATE_CONN_CLOSED - get QUIC stream
+state
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ #define SSL_STREAM_STATE_NONE
+ #define SSL_STREAM_STATE_OK
+ #define SSL_STREAM_STATE_WRONG_DIR
+ #define SSL_STREAM_STATE_FINISHED
+ #define SSL_STREAM_STATE_RESET_LOCAL
+ #define SSL_STREAM_STATE_RESET_REMOTE
+ #define SSL_STREAM_STATE_CONN_CLOSED
+
+ int SSL_get_stream_read_state(SSL *ssl);
+ int SSL_get_stream_write_state(SSL *ssl);
+
+ int SSL_get_stream_read_error_code(SSL *ssl, uint64_t *app_error_code);
+ int SSL_get_stream_write_error_code(SSL *ssl, uint64_t *app_error_code);
+
+=head1 DESCRIPTION
+
+SSL_get_stream_read_state() and SSL_get_stream_write_state() retrieve the
+overall state of the receiving and sending parts of a QUIC stream, respectively.
+
+They both return one of the following values:
+
+=over 4
+
+=item SSL_STREAM_STATE_NONE
+
+This value is returned if called on a non-QUIC SSL object, or on a QUIC
+connection SSL object without a default stream attached.
+
+=item SSL_STREAM_STATE_OK
+
+This value is returned on a stream which has not been concluded and remains
+healthy.
+
+=item SSL_STREAM_STATE_WRONG_DIR
+
+This value is returned if SSL_get_stream_read_state() is called on a
+locally-initiated (and thus send-only) unidirectional stream, or, conversely, if
+SSL_get_stream_write_state() is called on a remotely-initiated (and thus
+receive-only) unidirectional stream.
+
+=item SSL_STREAM_STATE_FINISHED
+
+For SSL_get_stream_read_state(), this value is returned when the remote peer has
+signalled the end of the receiving part of the stream. Note that there may still
+be residual data available to read via L<SSL_read(3)> when this state is
+returned.
+
+For SSL_get_stream_write_state(), this value is returned when the local
+application has concluded the stream using L<SSL_stream_conclude(3)>. Future
+L<SSL_write(3)> calls will not succeed.
+
+=item SSL_STREAM_STATE_RESET_LOCAL
+
+This value is returned when the applicable stream part was reset by the local
+application.
+
+For SSL_get_stream_read_state(), this means that the receiving part of the
+stream was aborted using a locally transmitted QUIC B<STOP_SENDING> frame. It
+may or may not still be possible to obtain any residual data which remains to be
+read by calling L<SSL_read(3)>.
+
+For SSL_get_stream_write_state(), this means that the sending part of the stream
+was aborted, for example because the application called L<SSL_stream_reset(3)>,
+or because a QUIC stream SSL object with an un-concluded sending part was freed
+using L<SSL_free(3)>. Calls to L<SSL_write(3)> will fail.
+
+When this value is returned, the application error code which was signalled can
+be obtained by calling SSL_get_stream_read_error_code() or
+SSL_get_stream_write_error_code() as appropriate.
+
+=item SSL_STREAM_STATE_RESET_REMOTE
+
+This value is returned when the applicable stream part was reset by the remote
+peer.
+
+For SSL_get_stream_read_state(), this means that the peer sent a QUIC
+B<RESET_STREAM> frame for the receiving part of the stream; the receiving part
+of the stream was logically aborted by the peer.
+
+For SSL_get_stream_write_state(), this means that the peer sent a QUIC
+B<STOP_SENDING> frame for the sending part of the stream; the peer has indicated
+that it does not wish to receive further data on the sending part of the stream.
+Calls to L<SSL_write(3)> will fail.
+
+When this value is returned, the application error code which was signalled can
+be obtained by calling SSL_get_stream_read_error_code() or
+SSL_get_stream_write_error_code() as appropriate.
+
+=item SSL_STREAM_STATE_CONN_CLOSED
+
+The QUIC connection to which the stream belongs was closed. You can obtain
+information about the circumstances of this closure using
+L<SSL_get_conn_close_info(3)>. There may still be residual data available to
+read via L<SSL_read(3)> when this state is returned. Calls to L<SSL_write(3)>
+will fail. SSL_get_stream_read_state() will return this state if and only if
+SSL_get_stream_write_state() will also return this state.
+
+=back
+
+SSL_get_stream_read_error_code() and SSL_get_stream_write_error_code() provide
+the application error code which was signalled during non-normal termination of
+the receiving or sending parts of a stream, respectively. On success, the
+application error code is written to B<*app_error_code>.
+
+=head1 NOTES
+
+If a QUIC connection is closed, the stream state for all streams transitions to
+B<SSL_STREAM_STATE_CONN_CLOSED>, but no application error code can be retrieved
+using SSL_get_stream_read_error_code() or SSL_get_stream_write_error_code(), as
+the QUIC connection closure process does not cause an application error code to
+be associated with each individual stream still existing at the time of
+connection closure. However, you can obtain the overall error code associated
+with the connection closure using L<SSL_get_conn_close_info(3)>.
+
+=head1 RETURN VALUES
+
+SSL_get_stream_read_state() and SSL_get_stream_write_state() return one of the
+B<SSL_STREAM_STATE> values. If called on a non-QUIC SSL object, or a QUIC
+connection SSL object without a default stream, B<SSL_STREAM_STATE_NONE> is
+returned.
+
+SSL_get_stream_read_error_code() and SSL_get_stream_write_error_code() return 1
+on success and 0 if the stream was terminated normally. They return -1 on error,
+for example if the stream is still healthy, was still healthy at the time of
+connection closure, if called on a stream for which the respective stream part
+does not exist (e.g. on a unidirectional stream), or if called on a non-QUIC
+object or a QUIC connection SSL object without a default stream attached.
+
+=head1 SEE ALSO
+
+L<SSL_stream_conclude(3)>, L<SSL_stream_reset(3)>, L<SSL_new_stream(3)>,
+L<SSL_accept_stream(3)>, L<SSL_get_conn_close_info(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2023 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_new_stream.pod b/doc/man3/SSL_new_stream.pod
new file mode 100644
index 0000000000..13f66474ab
--- /dev/null
+++ b/doc/man3/SSL_new_stream.pod
@@ -0,0 +1,62 @@
+=pod
+
+=head1 NAME
+
+SSL_new_stream, SSL_STREAM_FLAG_UNI - create a new locally-initiated QUIC stream
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ #define SSL_STREAM_FLAG_UNI     (1U << 0)
+ SSL *SSL_new_stream(SSL *ssl, uint64_t flags);
+
+=head1 DESCRIPTION
+
+The SSL_new_stream() function, when passed a QUIC connection SSL object, creates
+a new locally-initiated bidirectional or unidirectional QUIC stream and returns
+the newly created QUIC stream SSL object.
+
+If the B<SSL_STREAM_FLAG_UNI> flag is passed, a unidirectional stream is
+created; else a bidirectional stream is created.
+
+To retrieve the stream ID of the newly created stream, use
+L<SSL_get_stream_id(3)>.
+
+It is the caller's responsibility to free the QUIC stream SSL object using
+L<SSL_free(3)>. The lifetime of the QUIC connection SSL object must exceed that
+of the QUIC stream SSL object; in other words, the QUIC stream SSL object must
+be freed first.
+
+Once a stream has been created using SSL_new_stream(), it may be used in the
+normal way using L<SSL_read(3)> and L<SSL_write(3)>.
+
+This function can only be used to create stream objects for locally-initiated
+streams. To accept incoming streams initiated by a peer, use
+L<SSL_accept_stream(3)>.
+
+=head1 RETURN VALUES
+
+SSL_new_stream() returns a new stream object, or NULL on error.
+
+This function fails if called on a QUIC stream SSL object or on a non-QUIC SSL
+object.
+
+=head1 SEE ALSO
+
+L<SSL_accept_stream(3)>, L<SSL_free(3)>
+
+=head1 HISTORY
+
+SSL_new_stream() was added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2023 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_incoming_stream_reject_policy.pod b/doc/man3/SSL_set_incoming_stream_reject_policy.pod
new file mode 100644
index 0000000000..3e859b26ad
--- /dev/null
+++ b/doc/man3/SSL_set_incoming_stream_reject_policy.pod
@@ -0,0 +1,108 @@
+=pod
+
+=head1 NAME
+
+SSL_set_incoming_stream_reject_policy, SSL_INCOMING_STREAM_REJECT_POLICY_AUTO,
+SSL_INCOMING_STREAM_REJECT_POLICY_ACCEPT,
+SSL_INCOMING_STREAM_REJECT_POLICY_REJECT - manage the QUIC incoming stream
+rejection policy
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ #define SSL_INCOMING_STREAM_REJECT_POLICY_AUTO
+ #define SSL_INCOMING_STREAM_REJECT_POLICY_ACCEPT
+ #define SSL_INCOMING_STREAM_REJECT_POLICY_REJECT
+
+ int SSL_set_incoming_stream_reject_policy(SSL *conn, int policy,
+                                           uint64_t app_error_code);
+
+=head1 DESCRIPTION
+
+SSL_set_incoming_stream_reject_policy() policy changes the incoming stream
+rejection policy for a QUIC connection. Depending on the policy configured,
+OpenSSL QUIC may automatically reject incoming streams initiated by the peer.
+This is intended to ensure that legacy applications using single-stream
+operation with a default stream on a QUIC connection SSL object are not passed
+remotely-initiated streams by a peer which those applications are not prepared
+to handle.
+
+B<app_error_code> is an application error code which will be used in any QUIC
+B<STOP_SENDING> or B<RESET_STREAM> frames generated to implement the rejection
+policy. The default application error code is 0.
+
+The valid values for B<policy> are:
+
+=over 4
+
+=item SSL_INCOMING_STREAM_REJECT_POLICY_AUTO
+
+This is the default setting. Incoming streams are accepted according to the
+following rules:
+
+=over 4
+
+=item *
+
+An incoming stream is accepted if L<SSL_detach_stream(3)> has ever been called
+on a QUIC connection SSL object, as the application is assumed to be
+stream-aware in this case.
+
+=item *
+
+Otherwise, if the default stream mode (configured using
+L<SSL_set_default_stream_mode(3)>) is set to
+B<SSL_DEFAULT_STREAM_MODE_AUTO_BIDI> (the default) or
+B<SSL_DEFAULT_STREAM_MODE_AUTO_UNI>, the incoming stream is rejected.
+
+=item *
+
+Otherwise (where the default stream mode is B<SSL_DEFAULT_STREAM_MODE_NONE>),
+the application is assumed to be stream aware, and the incoming stream is
+accepted.
+
+=back
+
+=item SSL_INCOMING_STREAM_REJECT_POLICY_ACCEPT
+
+Always accept incoming streams, allowing them to be dequeued using
+L<SSL_accept_stream(3)>.
+
+=item SSL_INCOMING_STREAM_REJECT_POLICY_REJECT
+
+Always reject incoming streams.
+
+=back
+
+Where an incoming stream is rejected, it is rejected immediately and it is not
+possible to gain access to the stream using L<SSL_accept_stream(3)>. The stream
+is rejected using QUIC B<STOP_SENDING> and B<RESET_STREAM> frames as
+appropriate.
+
+=head1 RETURN VALUES
+
+Returns 1 on success and 0 on failure.
+
+This function fails if called on a QUIC stream SSL object, or on a non-QUIC SSL
+object.
+
+=head1 SEE ALSO
+
+L<SSL_attach_stream(3)>, L<SSL_detach_stream(3)>,
+L<SSL_set_default_stream_mode(3)>, L<SSL_accept_stream(3)>
+
+=head1 HISTORY
+
+SSL_set_incoming_stream_reject_policy() was added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2023 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_stream_reset.pod b/doc/man3/SSL_stream_reset.pod
new file mode 100644
index 0000000000..3f9159024a
--- /dev/null
+++ b/doc/man3/SSL_stream_reset.pod
@@ -0,0 +1,79 @@
+=pod
+
+=head1 NAME
+
+SSL_stream_reset - reset a QUIC stream
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ typedef struct ssl_stream_reset_args_st {
+     uint64_t quic_error_code;
+ } SSL_STREAM_RESET_ARGS;
+
+ int SSL_stream_reset(SSL *ssl,
+                      const SSL_STREAM_RESET_ARGS *args,
+                      size_t args_len);
+
+=head1 DESCRIPTION
+
+The SSL_stream_reset() function resets the send part of a QUIC stream when
+called on a QUIC stream SSL object, or on a QUIC connection SSL object with  a
+default stream attached.
+
+If B<args> is non-NULL, B<args_len> must be set to B<sizeof(*args)>.
+
+B<quic_error_code> is an application-specified error code, which must be in the
+range [0, 2**62-1]. If B<args> is NULL, a value of 0 is used.
+
+Resetting a stream indicates to an application that the sending part of the
+stream is terminating abnormally. When a stream is reset, the implementation
+does not guarantee that any data already passed to L<SSL_write(3)> will be
+received by the peer, and data already passed to L<SSL_write(3)> but not yet
+transmitted may or may not be discarded. As such, you should only reset
+a stream when the information transmitted on the stream no longer matters, for
+example due to an error condition.
+
+This function cannot be called on a unidirectional stream initiated by the peer,
+as only the sending side of a stream can initiate a stream reset.
+
+It is also possible to trigger a stream reset by calling L<SSL_free(3)>; see the
+documentation for L<SSL_free(3)> for details.
+
+The receiving part of the stream (for bidirectional streams) continues to
+function normally.
+
+=head1 NOTES
+
+This function corresponds to the QUIC B<RESET_STREAM> frame.
+
+=head1 RETURN VALUES
+
+Returns 1 on success and 0 on failure.
+
+This function fails if called on a QUIC connection SSL object without a default
+stream attached, or on a non-QUIC SSL object.
+
+After the first call to this function succeeds for a given stream,
+subsequent calls succeed but are ignored. The application error code
+used is that passed to the first successful call to this function.
+
+=head1 SEE ALSO
+
+L<SSL_free(3)>
+
+=head1 HISTORY
+
+SSL_stream_reset() was added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2023 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/util/other.syms b/util/other.syms
index daa3be067f..cecfe4d742 100644
--- a/util/other.syms
+++ b/util/other.syms
@@ -646,6 +646,25 @@ SSL_want_x509_lookup                    define
 SSLv23_client_method                    define
 SSLv23_method                           define
 SSLv23_server_method                    define
+SSL_STREAM_FLAG_UNI                     define
+SSL_STREAM_TYPE_NONE                    define
+SSL_STREAM_TYPE_READ                    define
+SSL_STREAM_TYPE_WRITE                   define
+SSL_STREAM_TYPE_BIDI                    define
+SSL_STREAM_STATE_NONE                   define
+SSL_STREAM_STATE_WRONG_DIR              define
+SSL_STREAM_STATE_OK                     define
+SSL_STREAM_STATE_FINISHED               define
+SSL_STREAM_STATE_RESET_LOCAL            define
+SSL_STREAM_STATE_RESET_REMOTE           define
+SSL_STREAM_STATE_CONN_CLOSED            define
+SSL_ACCEPT_STREAM_NO_BLOCK              define
+SSL_DEFAULT_STREAM_MODE_AUTO_BIDI       define
+SSL_DEFAULT_STREAM_MODE_AUTO_UNI        define
+SSL_DEFAULT_STREAM_MODE_NONE            define
+SSL_INCOMING_STREAM_REJECT_POLICY_ACCEPT define
+SSL_INCOMING_STREAM_REJECT_POLICY_AUTO  define
+SSL_INCOMING_STREAM_REJECT_POLICY_REJECT define
 TLS_DEFAULT_CIPHERSUITES                define deprecated 3.0.0
 X509_CRL_http_nbio                      define deprecated 3.0.0
 X509_http_nbio                          define deprecated 3.0.0