Debian Codegraph @

upstream/debian-unstable/man7/ossl-guide-quic-multi-stream.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL-GUIDE-QUIC-MULTI-STREAM 7SSL"
58 .TH OSSL-GUIDE-QUIC-MULTI-STREAM 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ossl\-guide\-quic\-multi\-stream
65 \&\- OpenSSL Guide: Writing a simple multi\-stream QUIC client
66 .SH INTRODUCTION
67 .IX Header "INTRODUCTION"
68 This page will introduce some important concepts required to write a simple
69 QUIC multi-stream application. It assumes a basic understanding of QUIC and how
70 it is used in OpenSSL. See \fBossl\-guide\-quic\-introduction\fR\|(7) and
71 \&\fBossl\-guide\-quic\-client\-block\fR\|(7).
72 .SH "QUIC STREAMS"
73 .IX Header "QUIC STREAMS"
74 In a QUIC multi-stream application we separate out the concepts of a QUIC
75 "connection" and a QUIC "stream". A connection object represents the overarching
76 details of the connection between a client and a server including all its
77 negotiated and configured parameters. We use the \fBSSL\fR object for that in an
78 OpenSSL application (known as the connection \fBSSL\fR object). It is created by an
79 application calling \fBSSL_new\fR\|(3).
80 .PP
81 Separately a connection can have zero or more streams associated with it
82 (although a connection with zero streams is probably not very useful, so
83 normally you would have at least one). A stream is used to send and receive
84 data between the two peers. Each stream is also represented by an \fBSSL\fR
85 object. A stream is logically independent of all the other streams associated
86 with the same connection. Data sent on a stream is guaranteed to be delivered
87 in the order that it was sent within that stream. The same is not true across
88 streams, e.g. if an application sends data on stream 1 first and then sends some
89 more data on stream 2 second, then the remote peer may receive the data sent on
90 stream 2 before it receives the data sent on stream 1.
91 .PP
92 Once the connection \fBSSL\fR object has completed its handshake (i.e.
93 \&\fBSSL_connect\fR\|(3) has returned 1), stream \fBSSL\fR objects are created by the
94 application calling \fBSSL_new_stream\fR\|(3) or \fBSSL_accept_stream\fR\|(3) (see
95 "CREATING NEW STREAMS" below).
96 .PP
97 The same threading rules apply to \fBSSL\fR objects as for most OpenSSL objects
98 (see \fBossl\-guide\-libraries\-introduction\fR\|(7)). In particular most OpenSSL
99 functions are thread safe, but the \fBSSL\fR object is not. This means that you can
100 use an \fBSSL\fR object representing one stream at the same time as another thread
101 is using a different \fBSSL\fR object for a different stream on the same
102 connection. But you cannot use the same \fBSSL\fR object on two different threads
103 at the same time (without additional application level locking).
104 .SH "THE DEFAULT STREAM"
105 .IX Header "THE DEFAULT STREAM"
106 A connection \fBSSL\fR object may also (optionally) be associated with a stream.
107 This stream is known as the default stream. The default stream is automatically
108 created and associated with the \fBSSL\fR object when the application calls
109 \&\fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) and
110 passes the connection \fBSSL\fR object as a parameter.
111 .PP
112 If a client application calls \fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) first then
113 (by default) the default stream will be a client-initiated bi-directional
114 stream. If a client application calls \fBSSL_read_ex\fR\|(3) or \fBSSL_read\fR\|(3)
115 first then the first stream initiated by the server will be used as the default
116 stream (whether it is bi-directional or uni-directional).
117 .PP
118 This behaviour can be controlled via the default stream mode. See
119 \&\fBSSL_set_default_stream_mode\fR\|(3) for further details.
120 .PP
121 It is recommended that new multi-stream applications should not use a default
122 stream at all and instead should use a separate stream \fBSSL\fR object for each
123 stream that is used. This requires calling \fBSSL_set_default_stream_mode\fR\|(3)
124 and setting the mode to \fBSSL_DEFAULT_STREAM_MODE_NONE\fR.
125 .SH "CREATING NEW STREAMS"
126 .IX Header "CREATING NEW STREAMS"
127 An endpoint can create a new stream by calling \fBSSL_new_stream\fR\|(3). This
128 creates a locally initiated stream. In order to do so you must pass the QUIC
129 connection \fBSSL\fR object as a parameter. You can also specify whether you want a
130 bi-directional or a uni-directional stream.
131 .PP
132 The function returns a new QUIC stream \fBSSL\fR object for sending and receiving
133 data on that stream.
134 .PP
135 The peer may also initiate streams. An application can use the function
136 \&\fBSSL_get_accept_stream_queue_len\fR\|(3) to determine the number of streams that
137 the peer has initiated that are waiting for the application to handle. An
138 application can call \fBSSL_accept_stream\fR\|(3) to create a new \fBSSL\fR object for
139 a remotely initiated stream. If the peer has not initiated any then this call
140 will block until one is available if the connection object is in blocking mode
141 (see \fBSSL_set_blocking_mode\fR\|(3)).
142 .PP
143 When using a default stream OpenSSL will prevent new streams from being
144 accepted. To override this behaviour you must call
145 \&\fBSSL_set_incoming_stream_policy\fR\|(3) to set the policy to
146 \&\fBSSL_INCOMING_STREAM_POLICY_ACCEPT\fR. See the man page for further details. This
147 is not relevant if the default stream has been disabled as described in
148 "THE DEFAULT STREAM" above.
149 .PP
150 Any stream may be bi-directional or uni-directional. If it is uni-directional
151 then the initiator can write to it but not read from it, and vice-versa for the
152 peer. You can determine what type of stream an \fBSSL\fR object represents by
153 calling \fBSSL_get_stream_type\fR\|(3). See the man page for further details.
154 .SH "USING A STREAM TO SEND AND RECEIVE DATA"
155 .IX Header "USING A STREAM TO SEND AND RECEIVE DATA"
156 Once you have a stream \fBSSL\fR object (which includes the connection \fBSSL\fR
157 object if a default stream is in use) then you can send and receive data over it
158 using the \fBSSL_write_ex\fR\|(3), \fBSSL_write\fR\|(3), \fBSSL_read_ex\fR\|(3) or
159 \&\fBSSL_read\fR\|(3) functions. See the man pages for further details.
160 .PP
161 In the event of one of these functions not returning a success code then
162 you should call \fBSSL_get_error\fR\|(3) to find out further details about the error.
163 In blocking mode this will either be a fatal error (e.g. \fBSSL_ERROR_SYSCALL\fR
164 or \fBSSL_ERROR_SSL\fR), or it will be \fBSSL_ERROR_ZERO_RETURN\fR which can occur
165 when attempting to read data from a stream and the peer has indicated that the
166 stream is concluded (i.e. "FIN" has been signalled on the stream). This means
167 that the peer will send no more data on that stream. Note that the
168 interpretation of \fBSSL_ERROR_ZERO_RETURN\fR is slightly different for a QUIC
169 application compared to a TLS application. In TLS it occurs when the connection
170 has been shutdown by the peer. In QUIC this only tells you that the current
171 stream has been concluded by the peer. It tells you nothing about the underlying
172 connection. If the peer has concluded the stream then no more data will be
173 received on it, however an application can still send data to the peer until
174 the send side of the stream has also been concluded. This can happen by the
175 application calling \fBSSL_stream_conclude\fR\|(3). It is an error to attempt to
176 send more data on a stream after \fBSSL_stream_conclude\fR\|(3) has been called.
177 .PP
178 It is also possible to abandon a stream abnormally by calling
179 \&\fBSSL_stream_reset\fR\|(3).
180 .PP
181 Once a stream object is no longer needed it should be freed via a call to
182 \&\fBSSL_free\fR\|(3). An application should not call \fBSSL_shutdown\fR\|(3) on it since
183 this is only meaningful for connection level \fBSSL\fR objects. Freeing the stream
184 will automatically signal STOP_SENDING to the peer.
185 .SH "STREAMS AND CONNECTIONS"
186 .IX Header "STREAMS AND CONNECTIONS"
187 Given a stream object it is possible to get the \fBSSL\fR object corresponding to
188 the connection via a call to \fBSSL_get0_connection\fR\|(3). Multi-threaded
189 restrictions apply so care should be taken when using the returned connection
190 object. Specifically, if you are handling each of your stream objects in a
191 different thread and call \fBSSL_get0_connection\fR\|(3) from within that thread then
192 you must be careful to not to call any function that uses the connection object
193 at the same time as one of the other threads is also using that connection
194 object (with the exception of \fBSSL_accept_stream\fR\|(3) and
195 \&\fBSSL_get_accept_stream_queue_len\fR\|(3) which are thread-safe).
196 .PP
197 A stream object does not inherit all its settings and values from its parent
198 \&\fBSSL\fR connection object. Therefore certain function calls that are relevant to
199 the connection as a whole will not work on a stream. For example the function
200 \&\fBSSL_get_certificate\fR\|(3) can be used to obtain a handle on the peer certificate
201 when called with a connection \fBSSL\fR object. When called with a stream \fBSSL\fR
202 object it will return NULL.
203 .SH "SIMPLE MULTI-STREAM QUIC CLIENT EXAMPLE"
204 .IX Header "SIMPLE MULTI-STREAM QUIC CLIENT EXAMPLE"
205 This section will present various source code samples demonstrating how to write
206 a simple multi-stream QUIC client application which connects to a server, send
207 some HTTP/1.0 requests to it, and read back the responses. Note that HTTP/1.0
208 over QUIC is non-standard and will not be supported by real world servers. This
209 is for demonstration purposes only.
210 .PP
211 We will build on the example code for the simple blocking QUIC client that is
212 covered on the \fBossl\-guide\-quic\-client\-block\fR\|(7) page and we assume that you
213 are familiar with it. We will only describe the differences between the simple
214 blocking QUIC client and the multi-stream QUIC client. Although the example code
215 uses blocking \fBSSL\fR objects, you can equally use nonblocking \fBSSL\fR objects.
216 See \fBossl\-guide\-quic\-client\-non\-block\fR\|(7) for more information about writing a
217 nonblocking QUIC client.
218 .PP
219 The complete source code for this example multi-stream QUIC client is available
220 in the \f(CW\*(C`demos/guide\*(C'\fR directory of the OpenSSL source distribution in the file
221 \&\f(CW\*(C`quic\-multi\-stream.c\*(C'\fR. It is also available online at
222 <https://github.com/openssl/openssl/blob/master/demos/guide/quic\-multi\-stream.c>.
223 .SS "Disabling the default stream"
224 .IX Subsection "Disabling the default stream"
225 As discussed above in "THE DEFAULT STREAM" we will follow the recommendation
226 to disable the default stream for our multi-stream client. To do this we call
227 the \fBSSL_set_default_stream_mode\fR\|(3) function and pass in our connection \fBSSL\fR
228 object and the value \fBSSL_DEFAULT_STREAM_MODE_NONE\fR.
229 .PP
230 .Vb 8
231 \& /*
232 \& * We will use multiple streams so we will disable the default stream mode.
233 \& * This is not a requirement for using multiple streams but is recommended.
234 \& */
235 \& if (!SSL_set_default_stream_mode(ssl, SSL_DEFAULT_STREAM_MODE_NONE)) {
236 \& printf("Failed to disable the default stream mode\en");
237 \& goto end;
238 \& }
239 .Ve
240 .SS "Creating the request streams"
241 .IX Subsection "Creating the request streams"
242 For the purposes of this example we will create two different streams to send
243 two different HTTP requests to the server. For the purposes of demonstration the
244 first of these will be a bi-directional stream and the second one will be a
245 uni-directional one:
246 .PP
247 .Vb 10
248 \& /*
249 \& * We create two new client initiated streams. The first will be
250 \& * bi\-directional, and the second will be uni\-directional.
251 \& */
252 \& stream1 = SSL_new_stream(ssl, 0);
253 \& stream2 = SSL_new_stream(ssl, SSL_STREAM_FLAG_UNI);
254 \& if (stream1 == NULL || stream2 == NULL) {
255 \& printf("Failed to create streams\en");
256 \& goto end;
257 \& }
258 .Ve
259 .SS "Writing data to the streams"
260 .IX Subsection "Writing data to the streams"
261 Once the streams are successfully created we can start writing data to them. In
262 this example we will be sending a different HTTP request on each stream. To
263 avoid repeating too much code we write a simple helper function to send an HTTP
264 request to a stream:
265 .PP
266 .Vb 5
267 \& int write_a_request(SSL *stream, const char *request_start,
268 \& const char *hostname)
269 \& {
270 \& const char *request_end = "\er\en\er\en";
271 \& size_t written;
272 \&
273 \& if (!SSL_write_ex(stream, request_start, strlen(request_start), &written))
274 \& return 0;
275 \& if (!SSL_write_ex(stream, hostname, strlen(hostname), &written))
276 \& return 0;
277 \& if (!SSL_write_ex(stream, request_end, strlen(request_end), &written))
278 \& return 0;
279 \&
280 \& return 1;
281 \& }
282 .Ve
283 .PP
284 We assume the strings \fBrequest1_start\fR and \fBrequest2_start\fR hold the
285 appropriate HTTP requests. We can then call our helper function above to send
286 the requests on the two streams. For the sake of simplicity this example does
287 this sequentially, writing to \fBstream1\fR first and, when this is successful,
288 writing to \fBstream2\fR second. Remember that our client is blocking so these
289 calls will only return once they have been successfully completed. A real
290 application would not need to do these writes sequentially or in any particular
291 order. For example we could start two threads (one for each stream) and write
292 the requests to each stream simultaneously.
293 .PP
294 .Vb 5
295 \& /* Write an HTTP GET request on each of our streams to the peer */
296 \& if (!write_a_request(stream1, request1_start, hostname)) {
297 \& printf("Failed to write HTTP request on stream 1\en");
298 \& goto end;
299 \& }
300 \&
301 \& if (!write_a_request(stream2, request2_start, hostname)) {
302 \& printf("Failed to write HTTP request on stream 2\en");
303 \& goto end;
304 \& }
305 .Ve
306 .SS "Reading data from a stream"
307 .IX Subsection "Reading data from a stream"
308 In this example \fBstream1\fR is a bi-directional stream so, once we have sent the
309 request on it, we can attempt to read the response from the server back. Here
310 we just repeatedly call \fBSSL_read_ex\fR\|(3) until that function fails (indicating
311 either that there has been a problem, or that the peer has signalled the stream
312 as concluded).
313 .PP
314 .Vb 10
315 \& printf("Stream 1 data:\en");
316 \& /*
317 \& * Get up to sizeof(buf) bytes of the response from stream 1 (which is a
318 \& * bidirectional stream). We keep reading until the server closes the
319 \& * connection.
320 \& */
321 \& while (SSL_read_ex(stream1, buf, sizeof(buf), &readbytes)) {
322 \& /*
323 \& * OpenSSL does not guarantee that the returned data is a string or
324 \& * that it is NUL terminated so we use fwrite() to write the exact
325 \& * number of bytes that we read. The data could be non\-printable or
326 \& * have NUL characters in the middle of it. For this simple example
327 \& * we\*(Aqre going to print it to stdout anyway.
328 \& */
329 \& fwrite(buf, 1, readbytes, stdout);
330 \& }
331 \& /* In case the response didn\*(Aqt finish with a newline we add one now */
332 \& printf("\en");
333 .Ve
334 .PP
335 In a blocking application like this one calls to \fBSSL_read_ex\fR\|(3) will either
336 succeed immediately returning data that is already available, or they will block
337 waiting for more data to become available and return it when it is, or they will
338 fail with a 0 response code.
339 .PP
340 Once we exit the while loop above we know that the last call to
341 \&\fBSSL_read_ex\fR\|(3) gave a 0 response code so we call the \fBSSL_get_error\fR\|(3)
342 function to find out more details. Since this is a blocking application this
343 will either return \fBSSL_ERROR_SYSCALL\fR or \fBSSL_ERROR_SSL\fR indicating a
344 fundamental problem, or it will return \fBSSL_ERROR_ZERO_RETURN\fR indicating that
345 the stream is concluded and there will be no more data available to read from
346 it. Care must be taken to distinguish between an error at the stream level (i.e.
347 a stream reset) and an error at the connection level (i.e. a connection closed).
348 The \fBSSL_get_stream_read_state\fR\|(3) function can be used to distinguish between
349 these different cases.
350 .PP
351 .Vb 12
352 \& /*
353 \& * Check whether we finished the while loop above normally or as the
354 \& * result of an error. The 0 argument to SSL_get_error() is the return
355 \& * code we received from the SSL_read_ex() call. It must be 0 in order
356 \& * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN. In
357 \& * QUIC terms this means that the peer has sent FIN on the stream to
358 \& * indicate that no further data will be sent.
359 \& */
360 \& switch (SSL_get_error(stream1, 0)) {
361 \& case SSL_ERROR_ZERO_RETURN:
362 \& /* Normal completion of the stream */
363 \& break;
364 \&
365 \& case SSL_ERROR_SSL:
366 \& /*
367 \& * Some stream fatal error occurred. This could be because of a stream
368 \& * reset \- or some failure occurred on the underlying connection.
369 \& */
370 \& switch (SSL_get_stream_read_state(stream1)) {
371 \& case SSL_STREAM_STATE_RESET_REMOTE:
372 \& printf("Stream reset occurred\en");
373 \& /* The stream has been reset but the connection is still healthy. */
374 \& break;
375 \&
376 \& case SSL_STREAM_STATE_CONN_CLOSED:
377 \& printf("Connection closed\en");
378 \& /* Connection is already closed. Skip SSL_shutdown() */
379 \& goto end;
380 \&
381 \& default:
382 \& printf("Unknown stream failure\en");
383 \& break;
384 \& }
385 \& break;
386 \&
387 \& default:
388 \& /* Some other unexpected error occurred */
389 \& printf ("Failed reading remaining data\en");
390 \& break;
391 \& }
392 .Ve
393 .SS "Accepting an incoming stream"
394 .IX Subsection "Accepting an incoming stream"
395 Our \fBstream2\fR object that we created above was a uni-directional stream so it
396 cannot be used to receive data from the server. In this hypothetical example
397 we assume that the server initiates a new stream to send us back the data that
398 we requested. To do that we call \fBSSL_accept_stream\fR\|(3). Since this is a
399 blocking application this will wait indefinitely until the new stream has
400 arrived and is available for us to accept. In the event of an error it will
401 return \fBNULL\fR.
402 .PP
403 .Vb 10
404 \& /*
405 \& * In our hypothetical HTTP/1.0 over QUIC protocol that we are using we
406 \& * assume that the server will respond with a server initiated stream
407 \& * containing the data requested in our uni\-directional stream. This doesn\*(Aqt
408 \& * really make sense to do in a real protocol, but its just for
409 \& * demonstration purposes.
410 \& *
411 \& * We\*(Aqre using blocking mode so this will block until a stream becomes
412 \& * available. We could override this behaviour if we wanted to by setting
413 \& * the SSL_ACCEPT_STREAM_NO_BLOCK flag in the second argument below.
414 \& */
415 \& stream3 = SSL_accept_stream(ssl, 0);
416 \& if (stream3 == NULL) {
417 \& printf("Failed to accept a new stream\en");
418 \& goto end;
419 \& }
420 .Ve
421 .PP
422 We can now read data from the stream in the same way that we did for \fBstream1\fR
423 above. We won't repeat that here.
424 .SS "Cleaning up the streams"
425 .IX Subsection "Cleaning up the streams"
426 Once we have finished using our streams we can simply free them by calling
427 \&\fBSSL_free\fR\|(3). Optionally we could call \fBSSL_stream_conclude\fR\|(3) on them if
428 we want to indicate to the peer that we won't be sending them any more data, but
429 we don't do that in this example because we assume that the HTTP application
430 protocol supplies sufficient information for the peer to know when we have
431 finished sending request data.
432 .PP
433 We should not call \fBSSL_shutdown\fR\|(3) or \fBSSL_shutdown_ex\fR\|(3) on the stream
434 objects since those calls should not be used for streams.
435 .PP
436 .Vb 3
437 \& SSL_free(stream1);
438 \& SSL_free(stream2);
439 \& SSL_free(stream3);
440 .Ve
441 .SH "SEE ALSO"
442 .IX Header "SEE ALSO"
443 \&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7),
444 \&\fBossl\-guide\-libssl\-introduction\fR\|(7) \fBossl\-guide\-quic\-introduction\fR\|(7),
445 \&\fBossl\-guide\-quic\-client\-block\fR\|(7)
446 .SH COPYRIGHT
447 .IX Header "COPYRIGHT"
448 Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.
449 .PP
450 Licensed under the Apache License 2.0 (the "License"). You may not use
451 this file except in compliance with the License. You can obtain a copy
452 in the file LICENSE in the source distribution or at
453 <https://www.openssl.org/source/license.html>.