From: Matt Caswell <matt@openssl.org>
Date: Mon, 21 Aug 2023 12:57:39 +0000 (+0100)
Subject: Clarify SSL_accept_stream/SSL_new_stream behaviour with a default stream
X-Git-Tag: openssl-3.2.0-alpha1~152
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a855ee857645614483976fb1be1b3907a2fe94d8;p=thirdparty%2Fopenssl.git

Clarify SSL_accept_stream/SSL_new_stream behaviour with a default stream

Explain what happens if you call those functions and there is no default
stream present yet.

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Hugo Landau <hlandau@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21765)
---

diff --git a/doc/man3/SSL_accept_stream.pod b/doc/man3/SSL_accept_stream.pod
index 2a5fe004fa4..d5055f50710 100644
--- a/doc/man3/SSL_accept_stream.pod
+++ b/doc/man3/SSL_accept_stream.pod
@@ -34,6 +34,9 @@ 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 I<flags>. If this flag is set,
 this function never blocks.
 
+Calling SSL_accept_stream() if there is no default stream already present
+inhibits the future creation of a default stream. See L<openssl-quic(7)>.
+
 SSL_get_accept_stream_queue_len() returns the number of incoming streams
 currently waiting in the accept queue.
 
diff --git a/doc/man3/SSL_new_stream.pod b/doc/man3/SSL_new_stream.pod
index 13f66474abe..7888cc44908 100644
--- a/doc/man3/SSL_new_stream.pod
+++ b/doc/man3/SSL_new_stream.pod
@@ -35,6 +35,9 @@ 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)>.
 
+Calling SSL_new_stream() if there is no default stream already present
+inhibits the future creation of a default stream. See L<openssl-quic(7)>.
+
 =head1 RETURN VALUES
 
 SSL_new_stream() returns a new stream object, or NULL on error.
diff --git a/doc/man7/openssl-quic.pod b/doc/man7/openssl-quic.pod
index 2ecf488d061..e4f73952f5e 100644
--- a/doc/man7/openssl-quic.pod
+++ b/doc/man7/openssl-quic.pod
@@ -97,6 +97,10 @@ in order to use L<SSL_accept_stream(3)> in this case. However, applications
 using additional streams are strongly recommended to use multi-stream mode
 instead.
 
+Calling L<SSL_new_stream(3)> or L<SSL_accept_stream(3)> before a default stream
+has been associated with the QUIC connection SSL object will inhibit future
+creation of a default stream.
+
 =head2 Multi-Stream Mode
 
 The recommended usage mode for new applications adopting QUIC is multi-stream
diff --git a/doc/man7/ossl-guide-quic-multi-stream.pod b/doc/man7/ossl-guide-quic-multi-stream.pod
index ba425ea7ea4..9956fff0949 100644
--- a/doc/man7/ossl-guide-quic-multi-stream.pod
+++ b/doc/man7/ossl-guide-quic-multi-stream.pod
@@ -99,15 +99,6 @@ B<SSL_INCOMING_STREAM_POLICY_ACCEPT>. See the man page for further details. This
 is not relevant if the default stream has been disabed as described in
 L</THE DEFAULT STREAM> above.
 
-=begin comment
-
-TODO(QUIC): What happens if SSL_accept_stream()/SSL_new_stream() is called and
-there is no default stream yet? incoming stream policy suggests that all
-incoming streams are rejected by default....but this only applies after a
-default stream has been created?
-
-=end comment
-
 Any stream may be bi-directional or uni-directional. If it is uni-directional
 then the initiator can write to it but not read from it, and vice-versa for the
 peer. You can determine what type of stream an B<SSL> object represents by