QUIC MSST: Documentation updates

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

4 files changed, 65 insertions, 14 deletions

diff --git a/doc/man3/SSL_accept_stream.pod b/doc/man3/SSL_accept_stream.pod
index 55c1868323..88fbb0db8d 100644
--- a/doc/man3/SSL_accept_stream.pod
+++ b/doc/man3/SSL_accept_stream.pod
@@ -36,22 +36,35 @@ 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.
+SSL_get_accept_stream_queue_len() returns the number of incoming streams
+currently waiting in the accept queue.
+
+=begin comment
+
+TODO(QUIC): Revise in MSMT PR to mention threading considerations.
+
+=end comment
 
 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)>.
 
+=begin comment
+
+TODO(QUIC): Update the above to refer to default stream man(7) page once
+man(7) pages are merged
+
+=end comment
+
 =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.
+no new incoming streams are available, or if the connection has been terminated,
+or if called on a SSL object other than a QUIC connection SSL object.
 
 SSL_get_accept_stream_queue_len() returns the number of incoming streams
-currently waiting in the accept queue.
+currently waiting in the accept queue, or 0 if called on a SSL object other than
+a QUIC connection SSL object.
 
 =head1 SEE ALSO
 
diff --git a/doc/man3/SSL_attach_stream.pod b/doc/man3/SSL_attach_stream.pod
index 45e40c82e5..e83224bbd0 100644
--- a/doc/man3/SSL_attach_stream.pod
+++ b/doc/man3/SSL_attach_stream.pod
@@ -60,7 +60,8 @@ 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 QUIC connection SSL object (for example, L<SSL_read(3)> and L<SSL_write(3)>)
+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
@@ -69,6 +70,13 @@ 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.
 
+If a stream is successfully attached to a QUIC connection SSL object using
+SSL_attach_stream(), the QUIC connection SSL object becomes responsible for
+managing its lifetime. Calling SSL_free() on the QUIC connection SSL object will
+free the stream automatically. Moreover, once the call to SSL_attach_stream()
+succeeds, the application must make no further use of the QUIC stream SSL object
+pointer that it passed to SSL_attach_stream().
+
 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.
@@ -89,9 +97,10 @@ 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)>.
+bidirectional or unidirectional; thus, this setting does not guarantee the
+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
 
diff --git a/doc/man3/SSL_free.pod b/doc/man3/SSL_free.pod
index d262f55d15..73c6065795 100644
--- a/doc/man3/SSL_free.pod
+++ b/doc/man3/SSL_free.pod
@@ -34,6 +34,34 @@ and L<SSL_set_shutdown(3)> was not used to set the
 SSL_SENT_SHUTDOWN state, the session will also be removed
 from the session cache as required by RFC2246.
 
+When used to free a QUIC stream SSL object, the respective sending and receiving
+parts of the stream are reset unless those parts have already been concluded
+normally:
+
+=over 4
+
+=item
+
+If the stream has a sending part (in other words, if it is bidirectional or a
+locally-initiated unidirectional stream) and that part has not been concluded
+via a call to L<SSL_stream_conclude(3)> or L<SSL_stream_reset(3)> on the QUIC
+stream SSL object, a call to SSL_free() automatically resets the sending part of
+the stream as though L<SSL_stream_reset(3)> were called with a QUIC application
+error code of 0.
+
+=item
+
+If the stream has a receiving part (in other words, if it is bidirectional or a
+remotely-initiated unidirectional stream), and the peer has not yet concluded
+that part of the stream normally (such as via a call to
+L<SSL_stream_conclude(3)> on its own end), a call to SSL_free() automatically
+requests the reset of the receiving part of the stream using a QUIC STOP_SENDING
+frame with a QUIC application error code of 0. Note that as per the QUIC
+protocol, this will automatically cause the peer to reset that part of the
+stream in turn (which is its sending part).
+
+=back
+
 =head1 RETURN VALUES
 
 SSL_free() does not provide diagnostic information.
diff --git a/doc/man3/SSL_get_stream_id.pod b/doc/man3/SSL_get_stream_id.pod
index b3ac31e3b2..b28c56e026 100644
--- a/doc/man3/SSL_get_stream_id.pod
+++ b/doc/man3/SSL_get_stream_id.pod
@@ -31,13 +31,14 @@ on the stream, and returns one of the following values:
 
 =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)>).
+The SSL object 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.
+The SSL object is a non-QUIC SSL object, or 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>