diff options
author | Matt Caswell <matt@openssl.org> | 2023-08-15 14:40:39 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2023-08-25 11:42:51 +0100 |
commit | 4a5ba9ae1325f2a02ab670b530a39568cb4f691f (patch) | |
tree | 45e172b9eae44954ab56ac9f93e565cac1e857f6 /doc/man7 | |
parent | f6225f4f692ab45c0e891f83a7782a7dcd211204 (diff) |
Provide introduction/tutorial page for QUIC multi-stream
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Hugo Landau <hlandau@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21765)
Diffstat (limited to 'doc/man7')
-rw-r--r-- | doc/man7/ossl-guide-quic-client-block.pod | 12 | ||||
-rw-r--r-- | doc/man7/ossl-guide-quic-multi-stream.pod | 335 |
2 files changed, 343 insertions, 4 deletions
diff --git a/doc/man7/ossl-guide-quic-client-block.pod b/doc/man7/ossl-guide-quic-client-block.pod index 551d6bbe4f..10658f9bc8 100644 --- a/doc/man7/ossl-guide-quic-client-block.pod +++ b/doc/man7/ossl-guide-quic-client-block.pod @@ -17,8 +17,8 @@ ossl-guide-quic-client-block This page will present various source code samples demonstrating how to write a simple blocking QUIC client application which connects to a server, sends an HTTP/1.0 request to it, and reads back the response. Note that HTTP/1.0 over -QUIC is non-standard and will not typically be supported by real world servers. -This is for demonstration purposes only. +QUIC is non-standard and will not be supported by real world servers. This is +for demonstration purposes only. We assume that you already have OpenSSL installed on your system; that you already have some fundamental understanding of OpenSSL concepts, TLS and QUIC @@ -33,7 +33,8 @@ this one will be discussed so we also assume that you have run through and understand that tutorial. For this tutorial our client will be using a single QUIC stream. A subsequent -tutorial will discuss how to write a multi-stream client. +tutorial will discuss how to write a multi-stream client (see +L<ossl-guide-quic-multi-stream(7)>). The complete source code for this example blocking QUIC client is available in the C<demos/guide> directory of the OpenSSL source distribution in the file @@ -288,6 +289,11 @@ 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 FURTHER READING + +See L<ossl-guide-quic-multi-stream(7)> to read a tutorial on how to modify the +client developed on this page to support multiple streams. + =head1 SEE ALSO L<ossl-guide-introduction(7)>, L<ossl-guide-libraries-introduction(7)>, diff --git a/doc/man7/ossl-guide-quic-multi-stream.pod b/doc/man7/ossl-guide-quic-multi-stream.pod index 030792ce43..ba425ea7ea 100644 --- a/doc/man7/ossl-guide-quic-multi-stream.pod +++ b/doc/man7/ossl-guide-quic-multi-stream.pod @@ -12,11 +12,344 @@ demos/guide/quic-multi-stream.c ossl-guide-quic-multi-stream - OpenSSL Guide: Writing a simple multi-stream QUIC client +=head1 INTRODUCTION + +This page will introduce some important concepts required to write a simple +QUIC multi-stream application. It assumes a basic understanding of QUIC and how +it is used in OpenSSL. See L<ossl-guide-quic-introduction(7)> and +L<ossl-guide-quic-client-block(7)>. + +=head1 QUIC STREAMS + +In a QUIC multi-stream application we separate out the concepts of a QUIC +"connection" and a QUIC "stream". A connection object represents the overarching +details of the connection between a client and a server including all its +negotiated and configured parameters. We use the B<SSL> object for that in an +OpenSSL application (known as the connection B<SSL> object). It is created by an +application calling L<SSL_new(3)>. + +Separately a connection can have zero or more streams associated with it +(although a connection with zero streams is probably not very useful, so +normally you would have at least one). A stream is used to send and receive +data between the two peers. Each stream is also represented by an B<SSL> +object. A stream is logically independent of all the other streams associated +with the same connection. Data sent on a stream is guaranteed to be delivered +in the order that it was sent within that stream. The same is not true across +streams, e.g. if an application sends data on stream 1 first and then sends some +more data on stream 2 second, then the remote peer may receive the data sent on +stream 2 before it receives the data sent on stream 1. + +Once the connection B<SSL> object has completed its handshake (i.e. +L<SSL_connect(3)> has returned 1), stream B<SSL> objects are created by the +application calling L<SSL_new_stream(3)> or L<SSL_accept_stream(3)> (see +L</CREATING NEW STREAMS> below). + +The same threading rules apply to B<SSL> objects as for most OpenSSL objects +(see L<ossl-guide-libraries-introduction(7)>). In particular most OpenSSL +functions are thread safe, but the B<SSL> object is not. This means that you can +use an B<SSL> object representing one stream at the same time as another thread +is using a different B<SSL> object for a different stream on the same +connection. But you cannot use the same B<SSL> object on two different threads +at the same time (without additional application level locking). + +=head1 THE DEFAULT STREAM + +A connection B<SSL> object may also (optionally) be associated with a stream. +This stream is known as the default stream. The default stream is automatically +created and associated with the B<SSL> object when the application calls +L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or L<SSL_write(3)> and +passes the connection B<SSL> object as a parameter. + +If a client application calls L<SSL_write_ex(3)> or L<SSL_write(3)> first then +(by default) the default stream will be a client-initiated bi-directional +stream. If the client applications call L<SSL_read_ex(3)> or L<SSL_read(3)> +first then the first stream initiated by the server will be used as the default +stream (whether it is bi-directional or uni-directional). + +This behaviour can be controlled via the default stream mode. See +L<SSL_set_default_stream_mode(3)> for further details. + +It is recommended that new multi-stream applications should not use a default +stream at all and instead should use a separate stream B<SSL> object for each +stream that is used. This requires calling L<SSL_set_default_stream_mode(3)> +and setting the mode to B<SSL_DEFAULT_STREAM_MODE_NONE>. + +=head1 CREATING NEW STREAMS + +An endpoint can create a new stream by calling L<SSL_new_stream(3)>. This +creates a locally initiated stream. In order to do so you must pass the QUIC +connection B<SSL> object as a parameter. You can also specify whether you want a +bi-directional or a uni-directional stream. + +The function returns a new QUIC stream B<SSL> object for sending and receiving +data on that stream. + +The peer may also initiate streams. An application can use the function +L<SSL_get_accept_stream_queue_len(3)> to determine the number of streams that +the peer has initiated that are waiting for the application to handle. An +application can call L<SSL_accept_stream(3)> to create a new B<SSL> object for +a remotely initiated stream. If the peer has not initiated any then this call +will block until one is available if the connection object is in blocking mode +(see L<SSL_set_blocking_mode(3)>). + +When using a default stream OpenSSL will prevent new streams from being +accepted. To override this behaviour you must call +L<SSL_set_incoming_stream_policy(3)> to set the policy to +B<SSL_INCOMING_STREAM_POLICY_ACCEPT>. See the man page for further details. This +is not relevant if the default stream has been disabed as described in +L</THE DEFAULT STREAM> above. + +=begin comment + +TODO(QUIC): What happens if SSL_accept_stream()/SSL_new_stream() is called and +there is no default stream yet? incoming stream policy suggests that all +incoming streams are rejected by default....but this only applies after a +default stream has been created? + +=end comment + +Any stream may be bi-directional or uni-directional. If it is uni-directional +then the initiator can write to it but not read from it, and vice-versa for the +peer. You can determine what type of stream an B<SSL> object represents by +calling L<SSL_get_stream_type(3)>. See the man page for further details. + +=head1 USING A STREAM TO SEND AND RECEIVE DATA + +Once you have a stream B<SSL> object (which includes the connection B<SSL> +object if a default stream is in use) then you can send and receive data over it +using the L<SSL_write_ex(3)>, L<SSL_write(3)>, L<SSL_read_ex(3)> or +L<SSL_read(3)> functions. See the man pages for further details. + +In the event of one of these functions not returning a success code then +you should call L<SSL_get_error(3)> to find out further details about the error. +In blocking mode this will either be a fatal error (e.g. B<SSL_ERROR_SYSCALL> +or B<SSL_ERROR_SSL>), or it will be B<SSL_ERROR_ZERO_RETURN> which can occur +when attempting to read data from a stream and the peer has indicated that the +stream is concluded (i.e. "FIN" has been signalled on the stream). This means +that the peer will send no more data on that stream. Note that the +interpretation of B<SSL_ERROR_ZERO_RETURN> is slightly different for a QUIC +application compared to a TLS application. In TLS it occurs when the connection +has been shutdown by the peer. In QUIC this only tells you that the current +stream has been concluded by the peer. It tells you nothing about the underlying +connection. If the peer has concluded the stream then no more data will be +received on it, however an application can still send data to the peer until +the send side of the stream has also been concluded. This can happen by the +application calling L<SSL_stream_conclude(3)>. It is an error to attempt to +send more data on a stream after L<SSL_stream_conclude(3)> has been called. + +It is also possible to abandon a stream abnormally by calling +L<SSL_stream_reset(3)>. + +=begin comment + +TODO(QUIC): What does SSL_get_error() return in the event that the +peer has reset a stream? If SSL_ERROR_SSL how does an application distinguish +between a stream reset and a connection level fatal error? + +=end comment + +Once a stream object is no longer needed it should be freed via a call to +L<SSL_free(3)>. An application should not call L<SSL_shutdown(3)> on it since +this is only meaningful for connection level B<SSL> objects. Freeing the stream +will automatically signal STOP_SENDING to the peer. + +=head1 STREAMS AND CONNECTIONS + +Given a stream object it is possible to get the B<SSL> object corresponding to +the connection via a call to L<SSL_get0_connection(3)>. Multi-threaded +restrictions apply so care should be taken when using the returned connection +object. Specifically, if you are handling each of your stream objects in a +different thread and call L<SSL_get0_connection(3)> from within that thread then +you must be careful to not to call any function that uses the connection object +at the same time as one of the other threads is also using that connection +object (with the exception of L<SSL_accept_stream(3)> and +L<SSL_get_accept_stream_queue_len(3)> which are thread-safe). + +A stream object does not inherit all its settings and values from its parent +B<SSL> connection object. Therefore certain function calls that are relevant to +the connection as a whole will not work on a stream. For example the function +L<SSL_get_certificate(3)> can be used to obtain a handle on the peer certificate +when called with a connection B<SSL> object. When called with a stream B<SSL> +object it will return NULL. + =head1 SIMPLE MULTI-STREAM QUIC CLIENT EXAMPLE -CONTENT HERE +This section will present various source code samples demonstrating how to write +a simple multi-stream QUIC client application which connects to a server, send +some HTTP/1.0 requests to it, and read back the responses. Note that HTTP/1.0 +over QUIC is non-standard and will not be supported by real world servers. This +is for demonstration purposes only. + +We will build on the example code for the simple blocking QUIC client that is +covered on the L<ossl-guide-quic-client-block(7)> page and we assume that you +are familiar with it. We will only describe the differences between the simple +blocking QUIC client and the multi-stream QUIC client. + +The complete source code for this example multi-stream QUIC client is available +in the C<demos/guide> directory of the OpenSSL source distribution in the file +C<quic-multi-stream.c>. It is also available online at +L<https://github.com/openssl/openssl/blob/master/demos/guide/quic-multi-stream.c>. + +=head2 Disabling the default stream + +As discussed above in L</THE DEFAULT STREAM> we will follow the recommendation +to disable the default stream for our multi-stream client. To do this we call +the L<SSL_set_default_stream_mode(3)> function and pass in our connection B<SSL> +object and the value B<SSL_DEFAULT_STREAM_MODE_NONE>. + + /* + * We will use multiple streams so we will disable the default stream mode. + * This is not a requirement for using multiple streams but is recommended. + */ + if (!SSL_set_default_stream_mode(ssl, SSL_DEFAULT_STREAM_MODE_NONE)) { + printf("Failed to disable the default stream mode\n"); + goto end; + } + +=head2 Creating the request streams + +For the purposes of this example we will create two different streams to send +two different HTTP requests to the server. For the purposes of demonstration the +first of these will be a bi-directional stream and the second one will be a +uni-directional one: + + /* + * We create two new client initiated streams. The first will be + * bi-directional, and the second will be uni-directional. + */ + stream1 = SSL_new_stream(ssl, 0); + stream2 = SSL_new_stream(ssl, SSL_STREAM_FLAG_UNI); + if (stream1 == NULL || stream2 == NULL) { + printf("Failed to create streams\n"); + goto end; + } + +=head2 Writing data to the streams + +Once the streams are successfully created we can start writing data to them. In +this example we will be sending a different HTTP request on each stream. We +assume the strings B<request1> and B<request2> hold the appropriate HTTP +requests. For the sake of simplicity this example does this sequentially, +writing to B<stream1> first and, when this is successful, writing to B<stream2> +second. Remember that our client is blocking so these calls will only return +once they have been successfully completed. A real application would not need to +do these writes sequentially or in any particular order. For example we could +start two threads (one for each stream) and write the requests to each stream +simultaneously. + + /* Write an HTTP GET request on each of our streams to the peer */ + if (!SSL_write_ex(stream1, request1, strlen(request1), &written)) { + printf("Failed to write HTTP request on stream 1\n"); + goto end; + } + + if (!SSL_write_ex(stream2, request2, strlen(request2), &written)) { + printf("Failed to write HTTP request on stream 2\n"); + goto end; + } + +=head2 Reading data from a stream + +In this example B<stream1> is a bi-directional stream so, once we have sent the +request on it, we can attempt to read the response from the server back. Here +we just repeatedly call L<SSL_read_ex(3)> until that function fails (indicating +either that there has been a problem, or that the peer has signalled the stream +as concluded). + + printf("Stream 1 data:\n"); + /* + * Get up to sizeof(buf) bytes of the response from stream 1 (which is a + * bidirectional stream). We keep reading until the server closes the + * connection. + */ + while (SSL_read_ex(stream1, buf, sizeof(buf), &readbytes)) { + /* + * OpenSSL does not guarantee that the returned data is a string or + * that it is NUL terminated so we use fwrite() to write the exact + * number of bytes that we read. The data could be non-printable or + * have NUL characters in the middle of it. For this simple example + * we're going to print it to stdout anyway. + */ + fwrite(buf, 1, readbytes, stdout); + } + /* In case the response didn't finish with a newline we add one now */ + printf("\n"); + +In a blocking application like this one calls to L<SSL_read_ex(3)> will either +succeed immediately returning data that is already available, or they will block +waiting for more data to become available and return it when it is, or they will +fail with a 0 response code. + +Once we exit the while loop above we know that the last call to +L<SSL_read_ex(3)> gave a 0 response code so we call the L<SSL_get_error(3)> +function to find out more details. Since this is a blocking application this +will either return B<SSL_ERROR_SYSCALL> or B<SSL_ERROR_SSL> indicating a +fundamental problem, or it will return B<SSL_ERROR_ZERO_RETURN> indicating that +the stream is concluded and there will be no more data available to read from +it. + + /* + * 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. 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(stream1, 0) != SSL_ERROR_ZERO_RETURN) { + /* + * Some error occurred other than a graceful close down by the + * peer. + */ + printf ("Failed reading remaining data from stream 1\n"); + goto end; + } + +=head2 Accepting an incoming stream + +Our B<stream2> object that we created above was a uni-directional stream so it +cannot be used to receive data from the server. In this hypothetical example +we assume that the server initiates a new stream to send us back the data that +we requested. To do that we call L<SSL_accept_stream(3)>. Since this is a +blocking application this will wait indefinitely until the new stream has +arrived and is available for us to accept. In the event of an error it will +return B<NULL>. + + /* + * In our hypothetical HTTP/1.0 over QUIC protocol that we are using we + * assume that the server will respond with a server initiated stream + * containing the data requested in our uni-directional stream. This doesn't + * really make sense to do in a real protocol, but its just for + * demonstration purposes. + * + * We're using blocking mode so this will block until a stream becomes + * available. We could override this behaviour if we wanted to by setting + * the SSL_ACCEPT_STREAM_NO_BLOCK flag in the second argument below. + */ + stream3 = SSL_accept_stream(ssl, 0); + if (stream3 == NULL) { + printf("Failed to accept a new stream\n"); + goto end; + } + +We can now read data from the stream in the same way that we did for B<stream1> +above. We won't repeat that here. + +=head2 Cleaning up the streams + +Once we have finished using our streams we can simply free them by calling +L<SSL_free(3)>. Optionally we could call L<SSL_stream_conclude(3)> on them if +we want to indicate to the peer that we won't be sending them any more data, but +we don't do that in this example because we assume that the HTTP application +protocol supplies sufficient information for the peer to know when we have +finished sending request data. +We should not call L<SSL_shutdown(3)> or L<SSL_shutdown_ex(3)> on the stream +objects since those calls should not be used for streams. + SSL_free(stream1); + SSL_free(stream2); + SSL_free(stream3); =head1 SEE ALSO |