Debian Codegraph @

upstream/debian-unstable/man7/ossl-guide-tls-client-non-block.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-TLS-CLIENT-NON-BLOCK 7SSL"
58 .TH OSSL-GUIDE-TLS-CLIENT-NON-BLOCK 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\-tls\-client\-non\-block
65 \&\- OpenSSL Guide: Writing a simple nonblocking TLS client
66 .SH "SIMPLE NONBLOCKING TLS CLIENT EXAMPLE"
67 .IX Header "SIMPLE NONBLOCKING TLS CLIENT EXAMPLE"
68 This page will build on the example developed on the
69 \&\fBossl\-guide\-tls\-client\-block\fR\|(7) page which demonstrates how to write a simple
70 blocking TLS client. On this page we will amend that demo code so that it
71 supports a nonblocking socket.
72 .PP
73 The complete source code for this example nonblocking TLS client is available
74 in the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file
75 \&\fBtls\-client\-non\-block.c\fR. It is also available online at
76 <https://github.com/openssl/openssl/blob/master/demos/guide/tls\-client\-non\-block.c>.
77 .PP
78 As we saw in the previous example a blocking socket is one which waits (blocks)
79 until data is available to read if you attempt to read from it when there is no
80 data yet. Similarly it waits when writing if the socket is currently unable to
81 write at the moment. This can simplify the development of code because you do
82 not have to worry about what to do in these cases. The execution of the code
83 will simply stop until it is able to continue. However in many cases you do not
84 want this behaviour. Rather than stopping and waiting your application may need
85 to go and do other tasks whilst the socket is unable to read/write, for example
86 updating a GUI or performing operations on some other socket.
87 .PP
88 With a nonblocking socket attempting to read or write to a socket that is
89 currently unable to read or write will return immediately with a non-fatal
90 error. Although OpenSSL does the reading/writing to the socket this nonblocking
91 behaviour is propagated up to the application so that OpenSSL I/O functions such
92 as \fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3) will not block.
93 .PP
94 Since this page is building on the example developed on the
95 \&\fBossl\-guide\-tls\-client\-block\fR\|(7) page we assume that you are familiar with it
96 and we only explain how this example differs.
97 .SS "Setting the socket to be nonblocking"
98 .IX Subsection "Setting the socket to be nonblocking"
99 The first step in writing an application that supports nonblocking is to set
100 the socket into nonblocking mode. A socket will be default be blocking. The
101 exact details on how to do this can differ from one platform to another.
102 Fortunately OpenSSL offers a portable function that will do this for you:
103 .PP
104 .Vb 5
105 \& /* Set to nonblocking mode */
106 \& if (!BIO_socket_nbio(sock, 1)) {
107 \& sock = \-1;
108 \& continue;
109 \& }
110 .Ve
111 .PP
112 You do not have to use OpenSSL's function for this. You can of course directly
113 call whatever functions that your Operating System provides for this purpose on
114 your platform.
115 .SS "Performing work while waiting for the socket"
116 .IX Subsection "Performing work while waiting for the socket"
117 In a nonblocking application you will need work to perform in the event that
118 we want to read or write to the socket, but we are currently unable to. In fact
119 this is the whole point of using a nonblocking socket, i.e. to give the
120 application the opportunity to do something else. Whatever it is that the
121 application has to do, it must also be prepared to come back and retry the
122 operation that it previously attempted periodically to see if it can now
123 complete. Ideally it would only do this in the event that the state of the
124 underlying socket has actually changed (e.g. become readable where it wasn't
125 before), but this does not have to be the case. It can retry at any time.
126 .PP
127 Note that it is important that you retry exactly the same operation that you
128 tried last time. You cannot start something new. For example if you were
129 attempting to write the text "Hello World" and the operation failed because the
130 socket is currently unable to write, then you cannot then attempt to write
131 some other text when you retry the operation.
132 .PP
133 In this demo application we will create a helper function which simulates doing
134 other work. In fact, for the sake of simplicity, it will do nothing except wait
135 for the state of the socket to change.
136 .PP
137 We call our function \f(CWwait_for_activity()\fR because all it does is wait until
138 the underlying socket has become readable or writeable when it wasn't before.
139 .PP
140 .Vb 4
141 \& static void wait_for_activity(SSL *ssl, int write)
142 \& {
143 \& fd_set fds;
144 \& int width, sock;
145 \&
146 \& /* Get hold of the underlying file descriptor for the socket */
147 \& sock = SSL_get_fd(ssl);
148 \&
149 \& FD_ZERO(&fds);
150 \& FD_SET(sock, &fds);
151 \& width = sock + 1;
152 \&
153 \& /*
154 \& * Wait until the socket is writeable or readable. We use select here
155 \& * for the sake of simplicity and portability, but you could equally use
156 \& * poll/epoll or similar functions
157 \& *
158 \& * NOTE: For the purposes of this demonstration code this effectively
159 \& * makes this demo block until it has something more useful to do. In a
160 \& * real application you probably want to go and do other work here (e.g.
161 \& * update a GUI, or service other connections).
162 \& *
163 \& * Let\*(Aqs say for example that you want to update the progress counter on
164 \& * a GUI every 100ms. One way to do that would be to add a 100ms timeout
165 \& * in the last parameter to "select" below. Then, when select returns,
166 \& * you check if it did so because of activity on the file descriptors or
167 \& * because of the timeout. If it is due to the timeout then update the
168 \& * GUI and then restart the "select".
169 \& */
170 \& if (write)
171 \& select(width, NULL, &fds, NULL, NULL);
172 \& else
173 \& select(width, &fds, NULL, NULL, NULL);
174 \& }
175 .Ve
176 .PP
177 In this example we are using the \f(CW\*(C`select\*(C'\fR function because it is very simple
178 to use and is available on most Operating Systems. However you could use any
179 other similar function to do the same thing. \f(CW\*(C`select\*(C'\fR waits for the state of
180 the underlying socket(s) to become readable/writeable before returning. It also
181 supports a "timeout" (as do most other similar functions) so in your own
182 applications you can make use of this to periodically wake up and perform work
183 while waiting for the socket state to change. But we don't use that timeout
184 capability in this example for the sake of simplicity.
185 .SS "Handling errors from OpenSSL I/O functions"
186 .IX Subsection "Handling errors from OpenSSL I/O functions"
187 An application that uses a nonblocking socket will need to be prepared to
188 handle errors returned from OpenSSL I/O functions such as \fBSSL_read_ex\fR\|(3) or
189 \&\fBSSL_write_ex\fR\|(3). Errors may be fatal (for example because the underlying
190 connection has failed), or non-fatal (for example because we are trying to read
191 from the underlying socket but the data has not yet arrived from the peer).
192 .PP
193 \&\fBSSL_read_ex\fR\|(3) and \fBSSL_write_ex\fR\|(3) will return 0 to indicate an error and
194 \&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) will return 0 or a negative value to indicate
195 an error. \fBSSL_shutdown\fR\|(3) will return a negative value to incidate an error.
196 .PP
197 In the event of an error an application should call \fBSSL_get_error\fR\|(3) to find
198 out what type of error has occurred. If the error is non-fatal and can be
199 retried then \fBSSL_get_error\fR\|(3) will return \fBSSL_ERROR_WANT_READ\fR or
200 \&\fBSSL_ERROR_WANT_WRITE\fR depending on whether OpenSSL wanted to read to or write
201 from the socket but was unable to. Note that a call to \fBSSL_read_ex\fR\|(3) or
202 \&\fBSSL_read\fR\|(3) can still generate \fBSSL_ERROR_WANT_WRITE\fR because OpenSSL
203 may need to write protocol messages (such as to update cryptographic keys) even
204 if the application is only trying to read data. Similarly calls to
205 \&\fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) might generate \fBSSL_ERROR_WANT_READ\fR.
206 .PP
207 Another type of non-fatal error that may occur is \fBSSL_ERROR_ZERO_RETURN\fR. This
208 indicates an EOF (End-Of-File) which can occur if you attempt to read data from
209 an \fBSSL\fR object but the peer has indicated that it will not send any more data
210 on it. In this case you may still want to write data to the connection but you
211 will not receive any more data.
212 .PP
213 Fatal errors that may occur are \fBSSL_ERROR_SYSCALL\fR and \fBSSL_ERROR_SSL\fR. These
214 indicate that the underlying connection has failed. You should not attempt to
215 shut it down with \fBSSL_shutdown\fR\|(3). \fBSSL_ERROR_SYSCALL\fR indicates that
216 OpenSSL attempted to make a syscall that failed. You can consult \fBerrno\fR for
217 further details. \fBSSL_ERROR_SSL\fR indicates that some OpenSSL error occurred. You
218 can consult the OpenSSL error stack for further details (for example by calling
219 \&\fBERR_print_errors\fR\|(3) to print out details of errors that have occurred).
220 .PP
221 In our demo application we will write a function to handle these errors from
222 OpenSSL I/O functions:
223 .PP
224 .Vb 7
225 \& static int handle_io_failure(SSL *ssl, int res)
226 \& {
227 \& switch (SSL_get_error(ssl, res)) {
228 \& case SSL_ERROR_WANT_READ:
229 \& /* Temporary failure. Wait until we can read and try again */
230 \& wait_for_activity(ssl, 0);
231 \& return 1;
232 \&
233 \& case SSL_ERROR_WANT_WRITE:
234 \& /* Temporary failure. Wait until we can write and try again */
235 \& wait_for_activity(ssl, 1);
236 \& return 1;
237 \&
238 \& case SSL_ERROR_ZERO_RETURN:
239 \& /* EOF */
240 \& return 0;
241 \&
242 \& case SSL_ERROR_SYSCALL:
243 \& return \-1;
244 \&
245 \& case SSL_ERROR_SSL:
246 \& /*
247 \& * If the failure is due to a verification error we can get more
248 \& * information about it from SSL_get_verify_result().
249 \& */
250 \& if (SSL_get_verify_result(ssl) != X509_V_OK)
251 \& printf("Verify error: %s\en",
252 \& X509_verify_cert_error_string(SSL_get_verify_result(ssl)));
253 \& return \-1;
254 \&
255 \& default:
256 \& return \-1;
257 \& }
258 \& }
259 .Ve
260 .PP
261 This function takes as arguments the \fBSSL\fR object that represents the
262 connection, as well as the return code from the I/O function that failed. In
263 the event of a non-fatal failure, it waits until a retry of the I/O operation
264 might succeed (by using the \f(CWwait_for_activity()\fR function that we developed
265 in the previous section). It returns 1 in the event of a non-fatal error
266 (except EOF), 0 in the event of EOF, or \-1 if a fatal error occurred.
267 .SS "Creating the SSL_CTX and SSL objects"
268 .IX Subsection "Creating the SSL_CTX and SSL objects"
269 In order to connect to a server we must create \fBSSL_CTX\fR and \fBSSL\fR objects for
270 this. The steps do this are the same as for a blocking client and are explained
271 on the \fBossl\-guide\-tls\-client\-block\fR\|(7) page. We won't repeat that information
272 here.
273 .SS "Performing the handshake"
274 .IX Subsection "Performing the handshake"
275 As in the demo for a blocking TLS client we use the \fBSSL_connect\fR\|(3) function
276 to perform the TLS handshake with the server. Since we are using a nonblocking
277 socket it is very likely that calls to this function will fail with a non-fatal
278 error while we are waiting for the server to respond to our handshake messages.
279 In such a case we must retry the same \fBSSL_connect\fR\|(3) call at a later time.
280 In this demo we this in a loop:
281 .PP
282 .Vb 7
283 \& /* Do the handshake with the server */
284 \& while ((ret = SSL_connect(ssl)) != 1) {
285 \& if (handle_io_failure(ssl, ret) == 1)
286 \& continue; /* Retry */
287 \& printf("Failed to connect to server\en");
288 \& goto end; /* Cannot retry: error */
289 \& }
290 .Ve
291 .PP
292 We continually call \fBSSL_connect\fR\|(3) until it gives us a success response.
293 Otherwise we use the \f(CWhandle_io_failure()\fR function that we created earlier to
294 work out what we should do next. Note that we do not expect an EOF to occur at
295 this stage, so such a response is treated in the same way as a fatal error.
296 .SS "Sending and receiving data"
297 .IX Subsection "Sending and receiving data"
298 As with the blocking TLS client demo we use the \fBSSL_write_ex\fR\|(3) function to
299 send data to the server. As with \fBSSL_connect\fR\|(3) above, because we are using
300 a nonblocking socket, this call could fail with a non-fatal error. In that case
301 we should retry exactly the same \fBSSL_write_ex\fR\|(3) call again. Note that the
302 parameters must be \fIexactly\fR the same, i.e. the same pointer to the buffer to
303 write with the same length. You must not attempt to send different data on a
304 retry. An optional mode does exist (\fBSSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\fR)
305 which will configure OpenSSL to allow the buffer being written to change from
306 one retry to the next. However, in this case, you must still retry exactly the
307 same data \- even though the buffer that contains that data may change location.
308 See \fBSSL_CTX_set_mode\fR\|(3) for further details. As in the TLS client
309 blocking tutorial (\fBossl\-guide\-tls\-client\-block\fR\|(7)) we write the request
310 in three chunks.
311 .PP
312 .Vb 10
313 \& /* Write an HTTP GET request to the peer */
314 \& while (!SSL_write_ex(ssl, request_start, strlen(request_start), &written)) {
315 \& if (handle_io_failure(ssl, 0) == 1)
316 \& continue; /* Retry */
317 \& printf("Failed to write start of HTTP request\en");
318 \& goto end; /* Cannot retry: error */
319 \& }
320 \& while (!SSL_write_ex(ssl, hostname, strlen(hostname), &written)) {
321 \& if (handle_io_failure(ssl, 0) == 1)
322 \& continue; /* Retry */
323 \& printf("Failed to write hostname in HTTP request\en");
324 \& goto end; /* Cannot retry: error */
325 \& }
326 \& while (!SSL_write_ex(ssl, request_end, strlen(request_end), &written)) {
327 \& if (handle_io_failure(ssl, 0) == 1)
328 \& continue; /* Retry */
329 \& printf("Failed to write end of HTTP request\en");
330 \& goto end; /* Cannot retry: error */
331 \& }
332 .Ve
333 .PP
334 On a write we do not expect to see an EOF response so we treat that case in the
335 same way as a fatal error.
336 .PP
337 Reading a response back from the server is similar:
338 .PP
339 .Vb 10
340 \& do {
341 \& /*
342 \& * Get up to sizeof(buf) bytes of the response. We keep reading until
343 \& * the server closes the connection.
344 \& */
345 \& while (!eof && !SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) {
346 \& switch (handle_io_failure(ssl, 0)) {
347 \& case 1:
348 \& continue; /* Retry */
349 \& case 0:
350 \& eof = 1;
351 \& continue;
352 \& case \-1:
353 \& default:
354 \& printf("Failed reading remaining data\en");
355 \& goto end; /* Cannot retry: error */
356 \& }
357 \& }
358 \& /*
359 \& * OpenSSL does not guarantee that the returned data is a string or
360 \& * that it is NUL terminated so we use fwrite() to write the exact
361 \& * number of bytes that we read. The data could be non\-printable or
362 \& * have NUL characters in the middle of it. For this simple example
363 \& * we\*(Aqre going to print it to stdout anyway.
364 \& */
365 \& if (!eof)
366 \& fwrite(buf, 1, readbytes, stdout);
367 \& } while (!eof);
368 \& /* In case the response didn\*(Aqt finish with a newline we add one now */
369 \& printf("\en");
370 .Ve
371 .PP
372 The main difference this time is that it is valid for us to receive an EOF
373 response when trying to read data from the server. This will occur when the
374 server closes down the connection after sending all the data in its response.
375 .PP
376 In this demo we just print out all the data we've received back in the response
377 from the server. We continue going around the loop until we either encounter a
378 fatal error, or we receive an EOF (indicating a graceful finish).
379 .SS "Shutting down the connection"
380 .IX Subsection "Shutting down the connection"
381 As in the TLS blocking example we must shutdown the connection when we are
382 finished with it.
383 .PP
384 If our application was initiating the shutdown then we would expect to see
385 \&\fBSSL_shutdown\fR\|(3) give a return value of 0, and then we would continue to call
386 it until we received a return value of 1 (meaning we have successfully completed
387 the shutdown). In this particular example we don't expect \fBSSL_shutdown()\fR to
388 return 0 because we have already received EOF from the server indicating that it
389 has shutdown already. So we just keep calling it until \fBSSL_shutdown()\fR returns 1.
390 Since we are using a nonblocking socket we might expect to have to retry this
391 operation several times. If \fBSSL_shutdown\fR\|(3) returns a negative result then we
392 must call \fBSSL_get_error\fR\|(3) to work out what to do next. We use our
393 \&\fBhandle_io_failure()\fR function that we developed earlier for this:
394 .PP
395 .Vb 10
396 \& /*
397 \& * The peer already shutdown gracefully (we know this because of the
398 \& * SSL_ERROR_ZERO_RETURN (i.e. EOF) above). We should do the same back.
399 \& */
400 \& while ((ret = SSL_shutdown(ssl)) != 1) {
401 \& if (ret < 0 && handle_io_failure(ssl, ret) == 1)
402 \& continue; /* Retry */
403 \& /*
404 \& * ret == 0 is unexpected here because that means "we\*(Aqve sent a
405 \& * close_notify and we\*(Aqre waiting for one back". But we already know
406 \& * we got one from the peer because of the SSL_ERROR_ZERO_RETURN
407 \& * (i.e. EOF) above.
408 \& */
409 \& printf("Error shutting down\en");
410 \& goto end; /* Cannot retry: error */
411 \& }
412 .Ve
413 .SS "Final clean up"
414 .IX Subsection "Final clean up"
415 As with the blocking TLS client example, once our connection is finished with we
416 must free it. The steps to do this for this example are the same as for the
417 blocking example, so we won't repeat it here.
418 .SH "FURTHER READING"
419 .IX Header "FURTHER READING"
420 See \fBossl\-guide\-tls\-client\-block\fR\|(7) to read a tutorial on how to write a
421 blocking TLS client. See \fBossl\-guide\-quic\-client\-block\fR\|(7) to see how to do the
422 same thing for a QUIC client.
423 .SH "SEE ALSO"
424 .IX Header "SEE ALSO"
425 \&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7),
426 \&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7),
427 \&\fBossl\-guide\-tls\-client\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7)
428 .SH COPYRIGHT
429 .IX Header "COPYRIGHT"
430 Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.
431 .PP
432 Licensed under the Apache License 2.0 (the "License"). You may not use
433 this file except in compliance with the License. You can obtain a copy
434 in the file LICENSE in the source distribution or at
435 <https://www.openssl.org/source/license.html>.