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 2a5fe004fa4fe4bf12da3af4420f00713b82468f..d5055f5071046b3c5eb8a9781a329f879d1b918a 100644 (file)
--- 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 13f66474abea3c4fa98277d318a5550ff122f794..7888cc44908a6f407f2db6a716df5218e396e9d7 100644 (file)
--- 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 2ecf488d0618a73faa6e174f64346077cd177a41..e4f73952f5e8713d459d2abac4b3f17c4437e8e2 100644 (file)
--- 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 ba425ea7ea49c3b897dab6c25a8525eda0a3075d..9956fff0949ad4df12ec5c577cf208e0c32e3632 100644 (file)
--- 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