From de521629c1f296a6eb50a84ab2d2b200fc766bc6 Mon Sep 17 00:00:00 2001 From: Hugo Landau Date: Tue, 9 May 2023 11:35:16 +0100 Subject: QUIC APL: De-publicise SSL_attach_stream/SSL_detach_stream Reviewed-by: Matt Caswell Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/20765) --- doc/build.info | 12 +- doc/man3/SSL_attach_stream.pod | 171 ---------------------------- doc/man3/SSL_get_stream_id.pod | 6 +- doc/man3/SSL_set_default_stream_mode.pod | 127 +++++++++++++++++++++ doc/man3/SSL_set_incoming_stream_policy.pod | 12 +- include/openssl/ssl.h.in | 3 - ssl/ssl_lib.c | 24 ---- test/quic_multistream_test.c | 5 +- util/libssl.num | 2 - 9 files changed, 141 insertions(+), 221 deletions(-) delete mode 100644 doc/man3/SSL_attach_stream.pod create mode 100644 doc/man3/SSL_set_default_stream_mode.pod 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_attach_stream.pod b/doc/man3/SSL_attach_stream.pod deleted file mode 100644 index 60f6315070..0000000000 --- a/doc/man3/SSL_attach_stream.pod +++ /dev/null @@ -1,171 +0,0 @@ -=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 - - 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 and L -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 or L 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 is called first (before any call to -L) 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 is called before any call to -L, 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. 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. - -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 and L) -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 or L 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. - -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, prior to initiating a connection. The argument -I may be one of the following options: - -=over 4 - -=item SSL_DEFAULT_STREAM_MODE_AUTO_BIDI - -This is the default setting. If L is called prior to any call to -L, a bidirectional client-initiated stream is created and bound as -the default stream. If L is called prior to any call to -L, OpenSSL waits for an incoming stream from the peer (causing -L 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 the -presence of a bidirectional stream when L is called first. To -determine the type of a stream after a call to L, use -L. - -=item SSL_DEFAULT_STREAM_MODE_AUTO_UNI - -In this mode, if L is called prior to any call to L, -a unidirectional client-initiated stream is created and bound as the default -stream. The behaviour is otherwise identical to that of -B. The behaviour when L is -called prior to any call to L is unchanged. - -=item SSL_DEFAULT_STREAM_MODE_NONE - -Default stream creation is inhibited. This is the recommended mode of operation. -L and L calls cannot be made on the QUIC connection -SSL object directly. You must obtain streams using L or -L 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, or -if the QUIC connection SSL object previously had a default stream which was -detached using SSL_detach_stream(). - -L 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, L, L, -L - -=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. - -=cut 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 -The SSL object is a QUIC connection SSL object without a default stream attached -(see L). +The SSL object is a QUIC connection SSL object without a default stream +attached. =item B @@ -81,7 +81,7 @@ SSL_get_stream_type() returns one of the B values. =head1 SEE ALSO -L, L, L +L, L =head1 HISTORY diff --git a/doc/man3/SSL_set_default_stream_mode.pod b/doc/man3/SSL_set_default_stream_mode.pod new file mode 100644 index 0000000000..bbdf59271d --- /dev/null +++ b/doc/man3/SSL_set_default_stream_mode.pod @@ -0,0 +1,127 @@ +=pod + +=head1 NAME + +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 + + #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 and L +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 or L 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 is called first (before any call to +L) 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 is called before any call to +L, 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. + +When a QUIC connection SSL object has no default stream currently associated +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 and L) 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 +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, prior to initiating a connection. The argument +I may be one of the following options: + +=over 4 + +=item SSL_DEFAULT_STREAM_MODE_AUTO_BIDI + +This is the default setting. If L is called prior to any call to +L, a bidirectional client-initiated stream is created and bound as +the default stream. If L is called prior to any call to +L, OpenSSL waits for an incoming stream from the peer (causing +L 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 the +presence of a bidirectional stream when L is called first. To +determine the type of a stream after a call to L, use +L. + +=item SSL_DEFAULT_STREAM_MODE_AUTO_UNI + +In this mode, if L is called prior to any call to L, +a unidirectional client-initiated stream is created and bound as the default +stream. The behaviour is otherwise identical to that of +B. The behaviour when L is +called prior to any call to L is unchanged. + +=item SSL_DEFAULT_STREAM_MODE_NONE + +Default stream creation is inhibited. This is the recommended mode of operation. +L and L calls cannot be made on the QUIC connection +SSL object directly. You must obtain streams using L or +L in order to communicate with the peer. + +=back + +A default stream will not be automatically created on a QUIC connection SSL +object if the default stream mode is set to B. + +L interacts significantly with the default +stream functionality. + +=head1 RETURN VALUES + +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, L, L, +L + +=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. + +=cut 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 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) is set to -B (the default) or +If the default stream mode (configured using L) +is set to B (the default) or B, the incoming stream is rejected. =item * @@ -89,7 +82,6 @@ object. =head1 SEE ALSO -L, L, L, L =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 #include #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: -- cgit v1.2.1