diff options
Diffstat (limited to 'upstream/archlinux/man7/ossl-guide-quic-client-non-block.7ssl')
| -rw-r--r-- | upstream/archlinux/man7/ossl-guide-quic-client-non-block.7ssl | 521 |
1 files changed, 521 insertions, 0 deletions
diff --git a/upstream/archlinux/man7/ossl-guide-quic-client-non-block.7ssl b/upstream/archlinux/man7/ossl-guide-quic-client-non-block.7ssl new file mode 100644 index 00000000..20956e31 --- /dev/null +++ b/upstream/archlinux/man7/ossl-guide-quic-client-non-block.7ssl @@ -0,0 +1,521 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-QUIC-CLIENT-NON-BLOCK 7ssl" +.TH OSSL-GUIDE-QUIC-CLIENT-NON-BLOCK 7ssl 2024-01-30 3.2.1 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-quic\-client\-non\-block +\&\- OpenSSL Guide: Writing a simple nonblocking QUIC client +.SH "SIMPLE NONBLOCKING QUIC CLIENT EXAMPLE" +.IX Header "SIMPLE NONBLOCKING QUIC CLIENT EXAMPLE" +This page will build on the example developed on the +\&\fBossl\-guide\-quic\-client\-block\fR\|(7) page which demonstrates how to write a simple +blocking QUIC client. On this page we will amend that demo code so that it +supports nonblocking functionality. +.PP +The complete source code for this example nonblocking QUIC client is available +in the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file +\&\fBquic\-client\-non\-block.c\fR. It is also available online at +<https://github.com/openssl/openssl/blob/master/demos/guide/quic\-client\-non\-block.c>. +.PP +As we saw in the previous example an OpenSSL QUIC application always uses a +nonblocking socket. However, despite this, the \fBSSL\fR object still has blocking +behaviour. When the \fBSSL\fR object has blocking behaviour then this means that +it waits (blocks) until data is available to read if you attempt to read from +it when there is no data yet. Similarly it waits when writing if the \fBSSL\fR +object is currently unable to write at the moment. This can simplify the +development of code because you do not have to worry about what to do in these +cases. The execution of the code will simply stop until it is able to continue. +However in many cases you do not want this behaviour. Rather than stopping and +waiting your application may need to go and do other tasks whilst the \fBSSL\fR +object is unable to read/write, for example updating a GUI or performing +operations on some other connection or stream. +.PP +We will see later in this tutorial how to change the \fBSSL\fR object so that it +has nonblocking behaviour. With a nonblocking \fBSSL\fR object, functions such as +\&\fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3) will return immediately with a non-fatal +error if they are currently unable to read or write respectively. +.PP +Since this page is building on the example developed on the +\&\fBossl\-guide\-quic\-client\-block\fR\|(7) page we assume that you are familiar with it +and we only explain how this example differs. +.SS "Performing work while waiting for the socket" +.IX Subsection "Performing work while waiting for the socket" +In a nonblocking application you will need work to perform in the event that +we want to read or write to the \fBSSL\fR object but we are currently unable to. +In fact this is the whole point of using a nonblocking \fBSSL\fR object, i.e. to +give the application the opportunity to do something else. Whatever it is that +the application has to do, it must also be prepared to come back and retry the +operation that it previously attempted periodically to see if it can now +complete. Ideally it would only do this in the event that something has changed +such that it might succeed on the retry attempt, but this does not have to be +the case. It can retry at any time. +.PP +Note that it is important that you retry exactly the same operation that you +tried last time. You cannot start something new. For example if you were +attempting to write the text "Hello World" and the operation failed because the +\&\fBSSL\fR object is currently unable to write, then you cannot then attempt to +write some other text when you retry the operation. +.PP +In this demo application we will create a helper function which simulates doing +other work. In fact, for the sake of simplicity, it will do nothing except wait +for the state of the underlying socket to change or until a timeout expires +after which the state of the \fBSSL\fR object might have changed. We will call our +function \f(CWwait_for_activity()\fR. +.PP +.Vb 6 +\& static void wait_for_activity(SSL *ssl) +\& { +\& fd_set wfds, rfds; +\& int width, sock, isinfinite; +\& struct timeval tv; +\& struct timeval *tvp = NULL; +\& +\& /* Get hold of the underlying file descriptor for the socket */ +\& sock = SSL_get_fd(ssl); +\& +\& FD_ZERO(&wfds); +\& FD_ZERO(&rfds); +\& +\& /* +\& * Find out if we would like to write to the socket, or read from it (or +\& * both) +\& */ +\& if (SSL_net_write_desired(ssl)) +\& FD_SET(sock, &wfds); +\& if (SSL_net_read_desired(ssl)) +\& FD_SET(sock, &rfds); +\& width = sock + 1; +\& +\& /* +\& * Find out when OpenSSL would next like to be called, regardless of +\& * whether the state of the underlying socket has changed or not. +\& */ +\& if (SSL_get_event_timeout(ssl, &tv, &isinfinite) && !isinfinite) +\& tvp = &tv; +\& +\& /* +\& * Wait until the socket is writeable or readable. We use select here +\& * for the sake of simplicity and portability, but you could equally use +\& * poll/epoll or similar functions +\& * +\& * NOTE: For the purposes of this demonstration code this effectively +\& * makes this demo block until it has something more useful to do. In a +\& * real application you probably want to go and do other work here (e.g. +\& * update a GUI, or service other connections). +\& * +\& * Let\*(Aqs say for example that you want to update the progress counter on +\& * a GUI every 100ms. One way to do that would be to use the timeout in +\& * the last parameter to "select" below. If the tvp value is greater +\& * than 100ms then use 100ms instead. Then, when select returns, you +\& * check if it did so because of activity on the file descriptors or +\& * because of the timeout. If the 100ms GUI timeout has expired but the +\& * tvp timeout has not then go and update the GUI and then restart the +\& * "select" (with updated timeouts). +\& */ +\& +\& select(width, &rfds, &wfds, NULL, tvp); +\&} +.Ve +.PP +If you are familiar with how to write nonblocking applications in OpenSSL for +TLS (see \fBossl\-guide\-tls\-client\-non\-block\fR\|(7)) then you should note that there +is an important difference here between the way a QUIC application and a TLS +application works. With a TLS application if we try to read or write something +to the \fBSSL\fR object and we get a "retry" response (\fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR) then we can assume that is because OpenSSL attempted to +read or write to the underlying socket and the socket signalled the "retry". +With QUIC that is not the case. OpenSSL may signal retry as a result of an +\&\fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3) (or similar) call which indicates the +state of the stream. This is entirely independent of whether the underlying +socket needs to retry or not. +.PP +To determine whether OpenSSL currently wants to read or write to the underlying +socket for a QUIC application we must call the \fBSSL_net_read_desired\fR\|(3) and +\&\fBSSL_net_write_desired\fR\|(3) functions. +.PP +It is also important with QUIC that we periodically call an I/O function (or +otherwise call the \fBSSL_handle_events\fR\|(3) function) to ensure that the QUIC +connection remains healthy. This is particularly important with a nonblocking +application because you are likely to leave the \fBSSL\fR object idle for a while +while the application goes off to do other work. The \fBSSL_get_event_timeout\fR\|(3) +function can be used to determine what the deadline is for the next time we need +to call an I/O function (or call \fBSSL_handle_events\fR\|(3)). +.PP +An alternative to using \fBSSL_get_event_timeout\fR\|(3) to find the next deadline +that OpenSSL must be called again by is to use "thread assisted" mode. In +"thread assisted" mode OpenSSL spawns an additional thread which will +periodically call \fBSSL_handle_events\fR\|(3) automatically, meaning that the +application can leave the connection idle safe in the knowledge that the +connection will still be maintained in a healthy state. See +"Creating the SSL_CTX and SSL objects" below for further details about this. +.PP +In this example we are using the \f(CW\*(C`select\*(C'\fR function to check the +readability/writeability of the socket because it is very simple to use and is +available on most Operating Systems. However you could use any other similar +function to do the same thing. \f(CW\*(C`select\*(C'\fR waits for the state of the underlying +socket(s) to become readable/writeable or until the timeout has expired before +returning. +.SS "Handling errors from OpenSSL I/O functions" +.IX Subsection "Handling errors from OpenSSL I/O functions" +A QUIC application that has been configured for nonblocking behaviour will need +to be prepared to handle errors returned from OpenSSL I/O functions such as +\&\fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3). Errors may be fatal for the stream (for +example because the stream has been reset or because the underlying connection +has failed), or non-fatal (for example because we are trying to read from the +stream but no data has not yet arrived from the peer for that stream). +.PP +\&\fBSSL_read_ex\fR\|(3) and \fBSSL_write_ex\fR\|(3) will return 0 to indicate an error and +\&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) will return 0 or a negative value to indicate +an error. \fBSSL_shutdown\fR\|(3) will return a negative value to incidate an error. +.PP +In the event of an error an application should call \fBSSL_get_error\fR\|(3) to find +out what type of error has occurred. If the error is non-fatal and can be +retried then \fBSSL_get_error\fR\|(3) will return \fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR depending on whether OpenSSL wanted to read to or write +from the stream but was unable to. Note that a call to \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_read\fR\|(3) can still generate \fBSSL_ERROR_WANT_WRITE\fR. Similarly calls to +\&\fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) might generate \fBSSL_ERROR_WANT_READ\fR. +.PP +Another type of non-fatal error that may occur is \fBSSL_ERROR_ZERO_RETURN\fR. This +indicates an EOF (End-Of-File) which can occur if you attempt to read data from +an \fBSSL\fR object but the peer has indicated that it will not send any more data +on the stream. In this case you may still want to write data to the stream but +you will not receive any more data. +.PP +Fatal errors that may occur are \fBSSL_ERROR_SYSCALL\fR and \fBSSL_ERROR_SSL\fR. These +indicate that the stream is no longer usable. For example, this could be because +the stream has been reset by the peer, or because the underlying connection has +failed. You can consult the OpenSSL error stack for further details (for example +by calling \fBERR_print_errors\fR\|(3) to print out details of errors that have +occurred). You can also consult the return value of +\&\fBSSL_get_stream_read_state\fR\|(3) to determine whether the error is local to the +stream, or whether the underlying connection has also failed. A return value +of \fBSSL_STREAM_STATE_RESET_REMOTE\fR tells you that the stream has been reset by +the peer and \fBSSL_STREAM_STATE_CONN_CLOSED\fR tells you that the underlying +connection has closed. +.PP +In our demo application we will write a function to handle these errors from +OpenSSL I/O functions: +.PP +.Vb 8 +\& static int handle_io_failure(SSL *ssl, int res) +\& { +\& switch (SSL_get_error(ssl, res)) { +\& case SSL_ERROR_WANT_READ: +\& case SSL_ERROR_WANT_WRITE: +\& /* Temporary failure. Wait until we can read/write and try again */ +\& wait_for_activity(ssl); +\& return 1; +\& +\& case SSL_ERROR_ZERO_RETURN: +\& /* EOF */ +\& return 0; +\& +\& case SSL_ERROR_SYSCALL: +\& return \-1; +\& +\& case SSL_ERROR_SSL: +\& /* +\& * Some stream fatal error occurred. This could be because of a +\& * stream reset \- or some failure occurred on the underlying +\& * connection. +\& */ +\& switch (SSL_get_stream_read_state(ssl)) { +\& case SSL_STREAM_STATE_RESET_REMOTE: +\& printf("Stream reset occurred\en"); +\& /* +\& * The stream has been reset but the connection is still +\& * healthy. +\& */ +\& break; +\& +\& case SSL_STREAM_STATE_CONN_CLOSED: +\& printf("Connection closed\en"); +\& /* Connection is already closed. */ +\& break; +\& +\& default: +\& printf("Unknown stream failure\en"); +\& break; +\& } +\& /* +\& * If the failure is due to a verification error we can get more +\& * information about it from SSL_get_verify_result(). +\& */ +\& if (SSL_get_verify_result(ssl) != X509_V_OK) +\& printf("Verify error: %s\en", +\& X509_verify_cert_error_string(SSL_get_verify_result(ssl))); +\& return \-1; +\& +\& default: +\& return \-1; +\& } +\& } +.Ve +.PP +This function takes as arguments the \fBSSL\fR object that represents the +connection, as well as the return code from the I/O function that failed. In +the event of a non-fatal failure, it waits until a retry of the I/O operation +might succeed (by using the \f(CWwait_for_activity()\fR function that we developed +in the previous section). It returns 1 in the event of a non-fatal error +(except EOF), 0 in the event of EOF, or \-1 if a fatal error occurred. +.SS "Creating the SSL_CTX and SSL objects" +.IX Subsection "Creating the SSL_CTX and SSL objects" +In order to connect to a server we must create \fBSSL_CTX\fR and \fBSSL\fR objects for +this. Most of the steps to do this are the same as for a blocking client and are +explained on the \fBossl\-guide\-quic\-client\-block\fR\|(7) page. We won't repeat that +information here. +.PP +One key difference is that we must put the \fBSSL\fR object into nonblocking mode +(the default is blocking mode). To do that we use the +\&\fBSSL_set_blocking_mode\fR\|(3) function: +.PP +.Vb 9 +\& /* +\& * The underlying socket is always nonblocking with QUIC, but the default +\& * behaviour of the SSL object is still to block. We set it for nonblocking +\& * mode in this demo. +\& */ +\& if (!SSL_set_blocking_mode(ssl, 0)) { +\& printf("Failed to turn off blocking mode\en"); +\& goto end; +\& } +.Ve +.PP +Although the demo application that we are developing here does not use it, it is +possible to use "thread assisted mode" when developing QUIC applications. +Normally, when writing an OpenSSL QUIC application, it is important that +\&\fBSSL_handle_events\fR\|(3) (or alternatively any I/O function) is called on the +connection \fBSSL\fR object periodically to maintain the connection in a healthy +state. See "Performing work while waiting for the socket" for more discussion +on this. This is particularly important to keep in mind when writing a +nonblocking QUIC application because it is common to leave the \fBSSL\fR connection +object idle for some time when using nonblocking mode. By using "thread assisted +mode" a separate thread is created by OpenSSL to do this automatically which +means that the application developer does not need to handle this aspect. To do +this we must use \fBOSSL_QUIC_client_thread_method\fR\|(3) when we construct the +\&\fBSSL_CTX\fR as shown below: +.PP +.Vb 5 +\& ctx = SSL_CTX_new(OSSL_QUIC_client_thread_method()); +\& if (ctx == NULL) { +\& printf("Failed to create the SSL_CTX\en"); +\& goto end; +\& } +.Ve +.SS "Performing the handshake" +.IX Subsection "Performing the handshake" +As in the demo for a blocking QUIC client we use the \fBSSL_connect\fR\|(3) function +to perform the handshake with the server. Since we are using a nonblocking +\&\fBSSL\fR object it is very likely that calls to this function will fail with a +non-fatal error while we are waiting for the server to respond to our handshake +messages. In such a case we must retry the same \fBSSL_connect\fR\|(3) call at a +later time. In this demo we do this in a loop: +.PP +.Vb 7 +\& /* Do the handshake with the server */ +\& while ((ret = SSL_connect(ssl)) != 1) { +\& if (handle_io_failure(ssl, ret) == 1) +\& continue; /* Retry */ +\& printf("Failed to connect to server\en"); +\& goto end; /* Cannot retry: error */ +\& } +.Ve +.PP +We continually call \fBSSL_connect\fR\|(3) until it gives us a success response. +Otherwise we use the \f(CWhandle_io_failure()\fR function that we created earlier to +work out what we should do next. Note that we do not expect an EOF to occur at +this stage, so such a response is treated in the same way as a fatal error. +.SS "Sending and receiving data" +.IX Subsection "Sending and receiving data" +As with the blocking QUIC client demo we use the \fBSSL_write_ex\fR\|(3) function to +send data to the server. As with \fBSSL_connect\fR\|(3) above, because we are using +a nonblocking \fBSSL\fR object, this call could fail with a non-fatal error. In +that case we should retry exactly the same \fBSSL_write_ex\fR\|(3) call again. Note +that the parameters must be \fIexactly\fR the same, i.e. the same pointer to the +buffer to write with the same length. You must not attempt to send different +data on a retry. An optional mode does exist +(\fBSSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\fR) which will configure OpenSSL to allow +the buffer being written to change from one retry to the next. However, in this +case, you must still retry exactly the same data \- even though the buffer that +contains that data may change location. See \fBSSL_CTX_set_mode\fR\|(3) for further +details. As in the TLS tutorials (\fBossl\-guide\-tls\-client\-block\fR\|(7)) we write +the request in three chunks. +.PP +.Vb 10 +\& /* Write an HTTP GET request to the peer */ +\& while (!SSL_write_ex(ssl, request_start, strlen(request_start), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write start of HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& while (!SSL_write_ex(ssl, hostname, strlen(hostname), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write hostname in HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& while (!SSL_write_ex(ssl, request_end, strlen(request_end), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write end of HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +.Ve +.PP +On a write we do not expect to see an EOF response so we treat that case in the +same way as a fatal error. +.PP +Reading a response back from the server is similar: +.PP +.Vb 10 +\& do { +\& /* +\& * Get up to sizeof(buf) bytes of the response. We keep reading until +\& * the server closes the connection. +\& */ +\& while (!eof && !SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) { +\& switch (handle_io_failure(ssl, 0)) { +\& case 1: +\& continue; /* Retry */ +\& case 0: +\& eof = 1; +\& continue; +\& case \-1: +\& default: +\& printf("Failed reading remaining data\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& } +\& /* +\& * 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\*(Aqre going to print it to stdout anyway. +\& */ +\& if (!eof) +\& fwrite(buf, 1, readbytes, stdout); +\& } while (!eof); +\& /* In case the response didn\*(Aqt finish with a newline we add one now */ +\& printf("\en"); +.Ve +.PP +The main difference this time is that it is valid for us to receive an EOF +response when trying to read data from the server. This will occur when the +server closes down the connection after sending all the data in its response. +.PP +In this demo we just print out all the data we've received back in the response +from the server. We continue going around the loop until we either encounter a +fatal error, or we receive an EOF (indicating a graceful finish). +.SS "Shutting down the connection" +.IX Subsection "Shutting down the connection" +As in the QUIC blocking example we must shutdown the connection when we are +finished with it. +.PP +Even though we have received EOF on the stream that we were reading from above, +this tell us nothing about the state of the underlying connection. Our demo +application will initiate the connection shutdown process via +\&\fBSSL_shutdown\fR\|(3). +.PP +Since our application is initiating the shutdown then we might expect to see +\&\fBSSL_shutdown\fR\|(3) give a return value of 0, and then we should continue to call +it until we receive a return value of 1 (meaning we have successfully completed +the shutdown). Since we are using a nonblocking \fBSSL\fR object we might expect to +have to retry this operation several times. If \fBSSL_shutdown\fR\|(3) returns a +negative result then we must call \fBSSL_get_error\fR\|(3) to work out what to do +next. We use our \fBhandle_io_failure()\fR function that we developed earlier for +this: +.PP +.Vb 8 +\& /* +\& * Repeatedly call SSL_shutdown() until the connection is fully +\& * closed. +\& */ +\& while ((ret = SSL_shutdown(ssl)) != 1) { +\& if (ret < 0 && handle_io_failure(ssl, ret) == 1) +\& continue; /* Retry */ +\& } +.Ve +.SS "Final clean up" +.IX Subsection "Final clean up" +As with the blocking QUIC client example, once our connection is finished with +we must free it. The steps to do this for this example are the same as for the +blocking example, so we won't repeat it here. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-quic\-client\-block\fR\|(7) to read a tutorial on how to write a +blocking QUIC client. See \fBossl\-guide\-quic\-multi\-stream\fR\|(7) to see how to write +a multi-stream QUIC client. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-quic\-introduction\fR\|(7), +\&\fBossl\-guide\-quic\-client\-block\fR\|(7), \fBossl\-guide\-quic\-multi\-stream\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. |