diff options
author | Hugo Landau <hlandau@openssl.org> | 2023-05-09 11:35:16 +0100 |
---|---|---|
committer | Hugo Landau <hlandau@openssl.org> | 2023-05-12 14:47:15 +0100 |
commit | de521629c1f296a6eb50a84ab2d2b200fc766bc6 (patch) | |
tree | 64effbd0fa8592a07cf7a322623c49697ab0c18f /doc | |
parent | 5da3e02c5eaac2bec9c14165d62874b1232213fe (diff) | |
download | openssl-new-de521629c1f296a6eb50a84ab2d2b200fc766bc6.tar.gz |
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/build.info | 12 | ||||
-rw-r--r-- | doc/man3/SSL_get_stream_id.pod | 6 | ||||
-rw-r--r-- | doc/man3/SSL_set_default_stream_mode.pod (renamed from doc/man3/SSL_attach_stream.pod) | 54 | ||||
-rw-r--r-- | doc/man3/SSL_set_incoming_stream_policy.pod | 12 |
4 files changed, 16 insertions, 68 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 |