From: Hugo Landau Date: Thu, 5 Jan 2023 08:35:07 +0000 (+0000) Subject: QUIC: Add documentation for stream and connection shutdown functions X-Git-Tag: openssl-3.2.0-alpha1~1372 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=522fb49dbcd283c00c77ebcc7a650c54ac6eba5b;p=thirdparty%2Fopenssl.git QUIC: Add documentation for stream and connection shutdown functions Reviewed-by: Tomas Mraz Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/19897) --- diff --git a/doc/build.info b/doc/build.info index 6ac83952e43..4be9146dce6 100644 --- a/doc/build.info +++ b/doc/build.info @@ -2671,6 +2671,10 @@ DEPEND[html/man3/SSL_state_string.html]=man3/SSL_state_string.pod GENERATE[html/man3/SSL_state_string.html]=man3/SSL_state_string.pod DEPEND[man/man3/SSL_state_string.3]=man3/SSL_state_string.pod GENERATE[man/man3/SSL_state_string.3]=man3/SSL_state_string.pod +DEPEND[html/man3/SSL_stream_conclude.html]=man3/SSL_stream_conclude.pod +GENERATE[html/man3/SSL_stream_conclude.html]=man3/SSL_stream_conclude.pod +DEPEND[man/man3/SSL_stream_conclude.3]=man3/SSL_stream_conclude.pod +GENERATE[man/man3/SSL_stream_conclude.3]=man3/SSL_stream_conclude.pod DEPEND[html/man3/SSL_tick.html]=man3/SSL_tick.pod GENERATE[html/man3/SSL_tick.html]=man3/SSL_tick.pod DEPEND[man/man3/SSL_tick.3]=man3/SSL_tick.pod @@ -3507,6 +3511,7 @@ html/man3/SSL_set_shutdown.html \ html/man3/SSL_set_verify_result.html \ html/man3/SSL_shutdown.html \ html/man3/SSL_state_string.html \ +html/man3/SSL_stream_conclude.html \ html/man3/SSL_tick.html \ html/man3/SSL_want.html \ html/man3/SSL_write.html \ @@ -4129,6 +4134,7 @@ man/man3/SSL_set_shutdown.3 \ man/man3/SSL_set_verify_result.3 \ man/man3/SSL_shutdown.3 \ man/man3/SSL_state_string.3 \ +man/man3/SSL_stream_conclude.3 \ man/man3/SSL_tick.3 \ man/man3/SSL_want.3 \ man/man3/SSL_write.3 \ diff --git a/doc/man3/SSL_shutdown.pod b/doc/man3/SSL_shutdown.pod index 6797006a283..f60f427bf6f 100644 --- a/doc/man3/SSL_shutdown.pod +++ b/doc/man3/SSL_shutdown.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_shutdown - shut down a TLS/SSL connection +SSL_shutdown, SSL_shutdown_ex - shut down a TLS/SSL or QUIC connection =head1 SYNOPSIS @@ -10,6 +10,15 @@ SSL_shutdown - shut down a TLS/SSL connection int SSL_shutdown(SSL *ssl); + typedef struct ssl_shutdown_ex_args_st { + uint64_t quic_error_code; + const char *quic_reason; + } SSL_SHUTDOWN_EX_ARGS; + + __owur int SSL_shutdown_ex(SSL *ssl, uint64_t flags, + const SSL_SHUTDOWN_EX_ARGS *args, + size_t args_len); + =head1 DESCRIPTION SSL_shutdown() shuts down an active TLS/SSL connection. It sends the @@ -88,6 +97,36 @@ will result in an error being generated. The error can be ignored using the B. For more information see L. +SSL_shutdown_ex() is an extended version of SSL_shutdown(). If non-NULL, I +must point to a B structure and I must be set to +I. The B structure must be +zero-initialized. If B is NULL, the behaviour is the same as passing a +zero-initialised B structure. When used with a non-QUIC +SSL object, the arguments are ignored and the call functions identically to +SSL_shutdown(). + +=begin comment + +TODO(QUIC): Once streams are implemented, revise this text + +=end comment + +When used with a QUIC connection SSL object, SSL_shutdown_ex() initiates a QUIC +immediate close. The I field can be used to specify a 62-bit +application error code to be signalled via QUIC. The value specified must be in +the range [0, 2**62-1], else this call fails. I may optionally +specify a zero-terminated reason string to be signalled to the peer. If a reason +is not specified, a zero-length string is used as the reason. The reason string +is copied and need not remain allocated after the call to the function returns. +Reason strings are bounded by the path MTU and may be silently truncated if they +are too long to fit in a QUIC packet. The arguments are only used on the first +call to SSL_shutdown_ex() for a given QUIC connection SSL object. + +When using QUIC, how an application uses SSL_shutdown() or SSL_shutdown_ex() has +implications for whether QUIC closes a connection in an RFC-compliant manner. +For discussion these issues, and for discussion of the I argument, see +B below. + =head2 First to close the connection When the application is the first party to send the close_notify @@ -125,9 +164,69 @@ If successful, SSL_shutdown() will return 1. Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the SSL_get_shutdown() (see also L call. +=head1 QUIC-SPECIFIC SHUTDOWN CONSIDERATIONS + +When using QUIC, SSL_shutdown() or SSL_shutdown_ex() causes any data written to +a stream which has not yet been sent to the peer to be written before the +shutdown process is considered complete. An exception to this is streams which +terminated in a non-normal fashion, for example due to a stream reset; only +streams which are non-terminated or which terminated in a normal fashion have +their pending send buffers flushed in this manner. This behaviour can be skipped +by setting the B flag; in this case, data remaining +in stream send buffers may not be transmitted to the peer. This flag may be used +when a non-normal application condition has occurred and the delivery of data +written to streams via L is no longer relevant. + +Aspects of how QUIC handles connection closure must be taken into account by +applications. Ordinarily, QUIC expects a connection to continue to be serviced +for a substantial period of time after it is nominally closed. This is necessary +to ensure that any connection closure notification sent to the peer was +successfully received. However, a consequence of this is that a fully +RFC-compliant QUIC connection closure process could take on the order of +seconds. This may be unsuitable for some applications, such as short-lived +processes which need to exit immediately after completing an application-layer +transaction. + +As such, there are two shutdown modes available to users of QUIC connection SSL +objects: + +=over 4 + +=item RFC compliant shutdown mode + +This is the default behaviour. The shutdown process may take a period of time up +to three times the current estimated RTT to the peer. It is possible for the +closure process to complete much faster in some circumstances but this cannot be +relied upon. + +In blocking mode, the function will return once the closure process is complete. +In nonblocking mode, SSL_shutdown_ex() should be called until it returns 1, +indicating the closure process is complete and the connection is now fully shut +down. + +=item Rapid shutdown mode + +In this mode, the peer is notified of connection closure on a best effort basis +by sending a single QUIC packet. If that QUIC packet i slost, the peer will not +know that the connection has terminated until the negotiated idle timeout (if +any) expires. + +This will generally return 0 on success, indicating that the connection has not +yet been fully shut down (unless it has already done so, in which case it will +return 1). + +=back + +If B is specified in I, a rapid shutdown is +performed, otherwise an RFC-compliant shutdown is performed. + +If an application calls SSL_shutdown_ex() with B, an +application can subsequently change its mind about performing a rapid shutdown +by making a subsequent call to SSL_shutdown_ex() without the flag set. + =head1 RETURN VALUES -The following return values can occur: +For both SSL_shutdown() and SSL_shutdown_ex() following return values can occur: =over 4 @@ -137,14 +236,19 @@ The shutdown is not yet finished: the close_notify was sent but the peer did not send it back yet. Call SSL_read() to do a bidirectional shutdown. -Unlike most other function, returning 0 does not indicate an error. -L should not get called, it may misleadingly +For QUIC connection SSL objects, a CONNECTION_CLOSE frame may have been sent +but the connection closure process has not yet completed. + +Unlike most other functions, returning 0 does not indicate an error. +L should not be called; it may misleadingly indicate an error even though no error occurred. =item Z<>1 -The shutdown was successfully completed. The close_notify alert was sent -and the peer's close_notify alert was received. +The shutdown was successfully completed. For non-QUIC SSL objects, this means +that the close_notify alert was sent and the peer's close_notify alert was +received. For QUIC connection SSL objects, this means that the connection +closure process has completed. =item E0 diff --git a/doc/man3/SSL_stream_conclude.pod b/doc/man3/SSL_stream_conclude.pod new file mode 100644 index 00000000000..88294a87593 --- /dev/null +++ b/doc/man3/SSL_stream_conclude.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +SSL_stream_conclude - conclude the sending part of a QUIC stream + +=head1 SYNOPSIS + + #include + + __owur int SSL_stream_conclude(SSL *s, uint64_t flags); + +=head1 DESCRIPTION + +SSL_stream_conclude() signals the normal end-of-stream condition for the send +part of a QUIC stream. If called on a QUIC connection SSL object, it signals the +end of the single stream to the peer. + +Any data already queued for transmission via a call to SSL_write() will still be +written in a reliable manner before the end-of-stream is signalled, assuming the +connection remains healthy. This function can be thought of as appending a +logical end-of-stream marker after any data which has previously been written to +the stream via calls to SSL_write(). Further attempts to call SSL_write() after +calling this function will fail. + +When calling this on a stream, the receive part of the stream remains +unaffected, and the peer may continue to send data until it also signals the end +of the stream. Thus, SSL_read() can still be used. + +B is reserved and should be set to 0. + +Only the first call to this function has any effect for a given stream; +subsequent calls are no-ops. This is considered a success case. + +=begin comment + +TODO(QUIC): Once streams are implemented, revise this text + +=end comment + +=head1 RETURN VALUES + +Returns 1 on success and 0 on failure. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +The SSL_stream_conclude() function was added in OpenSSL 3.2. + +=head1 COPYRIGHT + +Copyright 2022 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