| 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>. |