From b7f3d5d67d17aa1a384811014e79b461ce0e23ca Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Wed, 9 Aug 2023 17:43:13 +0100 Subject: [PATCH] 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 Reviewed-by: Hugo Landau (Merged from https://github.com/openssl/openssl/pull/21765) --- demos/guide/quic-client-block.c | 4 +- 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 cbe6deb7c11..7d3380675c9 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 a9826d5145f..ec6bc95e578 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 function. This example for QUIC is very similar to the TLS -version. However the L function may need to be called more than -once: +In the TLS tutorial we knew that the server had finished sending data because +L returned 0, and L returned +B. The same is true with QUIC except that +B 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 function. This example for QUIC is very similar +to the TLS version. However the L 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 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 that we had -obtained via L after the final L call. Due to -that return value we knew that the connection was already closed down for -receiving data and hence L should only need to be called once. - -However, with QUIC, the B value only tells us that the -stream (not the connection) is partially closed down. Therefore we need to call -L 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 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 will return 1 to indicate success. =head1 SEE ALSO -- 2.47.2