QUIC APL: De-publicise SSL_attach_stream/SSL_detach_stream

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

8 files changed, 19 insertions, 99 deletions

diff --git a/doc/build.info b/doc/build.info
index e501b455b9..197fead8d8 100644
--- a/doc/build.info
+++ b/doc/build.info
@@ -2459,10 +2459,6 @@ DEPEND[html/man3/SSL_alloc_buffers.html]=man3/SSL_alloc_buffers.pod
 GENERATE[html/man3/SSL_alloc_buffers.html]=man3/SSL_alloc_buffers.pod
 DEPEND[man/man3/SSL_alloc_buffers.3]=man3/SSL_alloc_buffers.pod
 GENERATE[man/man3/SSL_alloc_buffers.3]=man3/SSL_alloc_buffers.pod
-DEPEND[html/man3/SSL_attach_stream.html]=man3/SSL_attach_stream.pod
-GENERATE[html/man3/SSL_attach_stream.html]=man3/SSL_attach_stream.pod
-DEPEND[man/man3/SSL_attach_stream.3]=man3/SSL_attach_stream.pod
-GENERATE[man/man3/SSL_attach_stream.3]=man3/SSL_attach_stream.pod
 DEPEND[html/man3/SSL_check_chain.html]=man3/SSL_check_chain.pod
 GENERATE[html/man3/SSL_check_chain.html]=man3/SSL_check_chain.pod
 DEPEND[man/man3/SSL_check_chain.3]=man3/SSL_check_chain.pod
@@ -2679,6 +2675,10 @@ 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
 GENERATE[man/man3/SSL_set_connect_state.3]=man3/SSL_set_connect_state.pod
+DEPEND[html/man3/SSL_set_default_stream_mode.html]=man3/SSL_set_default_stream_mode.pod
+GENERATE[html/man3/SSL_set_default_stream_mode.html]=man3/SSL_set_default_stream_mode.pod
+DEPEND[man/man3/SSL_set_default_stream_mode.3]=man3/SSL_set_default_stream_mode.pod
+GENERATE[man/man3/SSL_set_default_stream_mode.3]=man3/SSL_set_default_stream_mode.pod
 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
@@ -3506,7 +3506,6 @@ html/man3/SSL_accept.html \
 html/man3/SSL_accept_stream.html \
 html/man3/SSL_alert_type_string.html \
 html/man3/SSL_alloc_buffers.html \
-html/man3/SSL_attach_stream.html \
 html/man3/SSL_check_chain.html \
 html/man3/SSL_clear.html \
 html/man3/SSL_connect.html \
@@ -3561,6 +3560,7 @@ 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_default_stream_mode.html \
 html/man3/SSL_set_fd.html \
 html/man3/SSL_set_incoming_stream_policy.html \
 html/man3/SSL_set_initial_peer_addr.html \
@@ -4141,7 +4141,6 @@ man/man3/SSL_accept.3 \
 man/man3/SSL_accept_stream.3 \
 man/man3/SSL_alert_type_string.3 \
 man/man3/SSL_alloc_buffers.3 \
-man/man3/SSL_attach_stream.3 \
 man/man3/SSL_check_chain.3 \
 man/man3/SSL_clear.3 \
 man/man3/SSL_connect.3 \
@@ -4196,6 +4195,7 @@ 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_default_stream_mode.3 \
 man/man3/SSL_set_fd.3 \
 man/man3/SSL_set_incoming_stream_policy.3 \
 man/man3/SSL_set_initial_peer_addr.3 \
diff --git a/doc/man3/SSL_get_stream_id.pod b/doc/man3/SSL_get_stream_id.pod
index b28c56e026..86ec2d9621 100644
--- a/doc/man3/SSL_get_stream_id.pod
+++ b/doc/man3/SSL_get_stream_id.pod
@@ -31,8 +31,8 @@ on the stream, and returns one of the following values:
 
 =item B<SSL_STREAM_TYPE_NONE>
 
-The SSL object 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.
 
 =item B<SSL_STREAM_TYPE_BIDI>
 
@@ -81,7 +81,7 @@ 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)>
+L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>
 
 =head1 HISTORY
 
diff --git a/doc/man3/SSL_attach_stream.pod b/doc/man3/SSL_set_default_stream_mode.pod
index 60f6315070..bbdf59271d 100644
--- a/doc/man3/SSL_attach_stream.pod
+++ b/doc/man3/SSL_set_default_stream_mode.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-SSL_attach_stream, SSL_detach_stream, SSL_set_default_stream_mode,
+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
@@ -11,9 +11,6 @@ connection
 
  #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
@@ -46,38 +43,10 @@ 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)>. A QUIC stream SSL
-object maintains a reference to a QUIC connection SSL object, therefore a QUIC
-connection SSL object and its child stream objects may be freed in either order;
-for details, see L<SSL_free(3)>.
-
 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 (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
-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.
-
-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(). An application must not call
-SSL_attach_stream() with a QUIC stream SSL object that has more than one
-reference to it.
+with it, for example because default stream functionality was disabled, calls to
+functions which require a stream on the QUIC connection SSL object (for example,
+L<SSL_read(3)> and L<SSL_write(3)>) will fail.
 
 It is recommended that new applications and applications which rely on multiple
 streams forego use of the default stream functionality, which is intended for
@@ -119,29 +88,16 @@ 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().
+object if the default stream mode is set to B<SSL_DEFAULT_STREAM_MODE_NONE>.
 
 L<SSL_set_incoming_stream_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
diff --git a/doc/man3/SSL_set_incoming_stream_policy.pod b/doc/man3/SSL_set_incoming_stream_policy.pod
index a89cbcfb94..da03445553 100644
--- a/doc/man3/SSL_set_incoming_stream_policy.pod
+++ b/doc/man3/SSL_set_incoming_stream_policy.pod
@@ -45,15 +45,8 @@ following rules:
 
 =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
+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 *
@@ -89,7 +82,6 @@ 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
diff --git a/include/openssl/ssl.h.in b/include/openssl/ssl.h.in
index 4d28522bf1..4e79ce5746 100644
--- a/include/openssl/ssl.h.in
+++ b/include/openssl/ssl.h.in
@@ -2282,9 +2282,6 @@ __owur uint64_t SSL_get_stream_id(SSL *s);
 #define SSL_DEFAULT_STREAM_MODE_AUTO_UNI    2
 __owur int SSL_set_default_stream_mode(SSL *s, uint32_t mode);
 
-__owur SSL *SSL_detach_stream(SSL *s);
-__owur int SSL_attach_stream(SSL *conn, SSL *stream);
-
 #define SSL_STREAM_FLAG_UNI     (1U << 0)
 __owur SSL *SSL_new_stream(SSL *s, uint64_t flags);
 
diff --git a/ssl/ssl_lib.c b/ssl/ssl_lib.c
index 4be70ce60f..567396caa4 100644
--- a/ssl/ssl_lib.c
+++ b/ssl/ssl_lib.c
@@ -7361,30 +7361,6 @@ int SSL_set_default_stream_mode(SSL *s, uint32_t mode)
 #endif
 }
 
-SSL *SSL_detach_stream(SSL *s)
-{
-#ifndef OPENSSL_NO_QUIC
-    if (!IS_QUIC(s))
-        return NULL;
-
-    return ossl_quic_detach_stream(s);
-#else
-    return NULL;
-#endif
-}
-
-int SSL_attach_stream(SSL *conn, SSL *stream)
-{
-#ifndef OPENSSL_NO_QUIC
-    if (!IS_QUIC(conn))
-        return 0;
-
-    return ossl_quic_attach_stream(conn, stream);
-#else
-    return 0;
-#endif
-}
-
 int SSL_set_incoming_stream_policy(SSL *s, int policy, uint64_t aec)
 {
 #ifndef OPENSSL_NO_QUIC
diff --git a/test/quic_multistream_test.c b/test/quic_multistream_test.c
index dbfdde0f4c..2fd8a2235f 100644
--- a/test/quic_multistream_test.c
+++ b/test/quic_multistream_test.c
@@ -11,6 +11,7 @@
 #include <openssl/bio.h>
 #include <openssl/lhash.h>
 #include "internal/quic_tserver.h"
+#include "internal/quic_ssl.h"
 #include "testutil.h"
 
 static const char *certfile, *keyfile;
@@ -715,7 +716,7 @@ static int run_script(const struct script_op *script, int free_order)
                 if (!TEST_ptr_null(c_tgt))
                     goto out; /* don't overwrite existing stream with same name */
 
-                if (!TEST_ptr(c_stream = SSL_detach_stream(h.c_conn)))
+                if (!TEST_ptr(c_stream = ossl_quic_detach_stream(h.c_conn)))
                     goto out;
 
                 if (!TEST_true(helper_set_c_stream(&h, op->stream_name, c_stream)))
@@ -728,7 +729,7 @@ static int run_script(const struct script_op *script, int free_order)
                 if (!TEST_ptr(c_tgt))
                     goto out;
 
-                if (!TEST_true(SSL_attach_stream(h.c_conn, c_tgt)))
+                if (!TEST_true(ossl_quic_attach_stream(h.c_conn, c_tgt)))
                     goto out;
 
                 if (!TEST_true(helper_set_c_stream(&h, op->stream_name, NULL)))
diff --git a/util/libssl.num b/util/libssl.num
index b850045694..bd1e12934e 100644
--- a/util/libssl.num
+++ b/util/libssl.num
@@ -566,8 +566,6 @@ SSL_is_connection                       ?	3_2_0	EXIST::FUNCTION:
 SSL_get_stream_type                     ?	3_2_0	EXIST::FUNCTION:
 SSL_get_stream_id                       ?	3_2_0	EXIST::FUNCTION:
 SSL_set_default_stream_mode             ?	3_2_0	EXIST::FUNCTION:
-SSL_detach_stream                       ?	3_2_0	EXIST::FUNCTION:
-SSL_attach_stream                       ?	3_2_0	EXIST::FUNCTION:
 SSL_accept_stream                       ?	3_2_0	EXIST::FUNCTION:
 SSL_get_accept_stream_queue_len         ?	3_2_0	EXIST::FUNCTION:
 SSL_stream_reset                        ?	3_2_0	EXIST::FUNCTION: