diff options
author | Matt Caswell <matt@openssl.org> | 2023-08-09 17:43:13 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2023-08-25 11:42:51 +0100 |
commit | b7f3d5d67d17aa1a384811014e79b461ce0e23ca (patch) | |
tree | 3bbb0e061060e72d677eb374be4468baad1563c8 | |
parent | 8c5284ff194f444877ae25012d3d07ee46e46219 (diff) |
Update the desciption of shutdown in the QUIC client blocking tutorial
Give a better description of the shutdown process in QUIC.
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Hugo Landau <hlandau@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21765)
-rw-r--r-- | demos/guide/quic-client-block.c | 4 | ||||
-rw-r--r-- | doc/man7/ossl-guide-quic-client-block.pod | 49 |
2 files changed, 33 insertions, 20 deletions
diff --git a/demos/guide/quic-client-block.c b/demos/guide/quic-client-block.c index cbe6deb7c1..7d3380675c 100644 --- a/demos/guide/quic-client-block.c +++ b/demos/guide/quic-client-block.c @@ -245,7 +245,9 @@ int main(void) * Check whether we finished the while loop above normally or as the * result of an error. The 0 argument to SSL_get_error() is the return * code we received from the SSL_read_ex() call. It must be 0 in order - * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN. + * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN. In + * QUIC terms this means that the peer has sent FIN on the stream to + * indicate that no further data will be sent. */ if (SSL_get_error(ssl, 0) != SSL_ERROR_ZERO_RETURN) { /* diff --git a/doc/man7/ossl-guide-quic-client-block.pod b/doc/man7/ossl-guide-quic-client-block.pod index a9826d5145..ec6bc95e57 100644 --- a/doc/man7/ossl-guide-quic-client-block.pod +++ b/doc/man7/ossl-guide-quic-client-block.pod @@ -244,11 +244,25 @@ the same way as for TLS. Again, we won't repeat it here. =head2 Shutting down the connection -As in the TLS tutorial, once we have finished reading data from the server then -we are ready to close the connection down. As before we do this via the -L<SSL_shutdown(3)> function. This example for QUIC is very similar to the TLS -version. However the L<SSL_shutdown(3)> function may need to be called more than -once: +In the TLS tutorial we knew that the server had finished sending data because +L<SSL_read_ex(3)> returned 0, and L<SSL_get_error(3)> returned +B<SSL_ERROR_ZERO_RETURN>. The same is true with QUIC except that +B<SSL_ERROR_ZERO_RETURN> should be interpreted slightly differently. With TLS +we knew that this meant that the server had sent a "close_notify" alert. No +more data will be sent from the server on that connection. + +With QUIC it means that the server has indicated "FIN" on the stream, meaning +that it will no longer send any more data on that stream. However this only +gives us information about the stream itself and does not tell us anything about +the underlying connection. More data could still be sent from the server on some +other stream. Additionally, although the server will not send any more data to +the client, it does not prevent the client from sending more data to the server. + +In this tutorial, once we have finished reading data from the server on the one +stream that we are using, we will close the connection down. As before we do +this via the L<SSL_shutdown(3)> function. This example for QUIC is very similar +to the TLS version. However the L<SSL_shutdown(3)> function will need to be +called more than once: /* * Repeatedly call SSL_shutdown() until the connection is fully @@ -262,20 +276,17 @@ once: } } while (ret != 1); -The shutdown process is in two stages. First we gracefully shutdown the -connection for sending and secondly we shutdown the connection for receiving. -L<SSL_shutdown(3)> returns 0 once the first stage has been completed, and 1 once -the second stage is finished. This two stage process applies to TLS as well. -However in our blocking TLS client example code we knew that the peer had -already partially closed down due to the B<SSL_ERROR_ZERO_RETURN> that we had -obtained via L<SSL_get_error(3)> after the final L<SSL_read_ex(3)> call. Due to -that return value we knew that the connection was already closed down for -receiving data and hence L<SSL_shutdown(3)> should only need to be called once. - -However, with QUIC, the B<SSL_ERROR_ZERO_RETURN> value only tells us that the -stream (not the connection) is partially closed down. Therefore we need to call -L<SSL_shutdown(3)> more than once to ensure that we progress through both stages -of the shutdown process. +The shutdown process is in two stages. In the first stage we wait until all the +data we have buffered for sending on any stream has been successfully sent and +acknowledged by the peer, and then we send a CONNECTION_CLOSE to the peer to +indicate that the connection is no longer usable. This immediately closes the +connection and no more data can be sent or received. L<SSL_shutdown(3)> returns +0 once the first stage has been completed. + +In the second stage the connection enters a "closing" state. Application data +cannot be sent or received in this state, but late arriving packets coming from +the peer will be handled appropriately. Once this stage has completed +successfully L<SSL_shutdown(3)> will return 1 to indicate success. =head1 SEE ALSO |