doc/man7/ossl-guide-quic-client-non-block.pod - third_party/openssl - Git at Google

 =pod

 =begin comment

 NB: Changes to the source code samples in this file should also be reflected in
 demos/guide/quic-client-non-block.c

 =end comment

 =head1 NAME

 ossl-guide-quic-client-non-block
 - OpenSSL Guide: Writing a simple nonblocking QUIC client

 =head1 SIMPLE NONBLOCKING QUIC CLIENT EXAMPLE

 This page will build on the example developed on the
 L<ossl-guide-quic-client-block(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.

 The complete source code for this example nonblocking QUIC client is available
 in the B<demos/guide> directory of the OpenSSL source distribution in the file
 B<quic-client-non-block.c>. It is also available online at
 L<https://github.com/openssl/openssl/blob/master/demos/guide/quic-client-non-block.c>.

 As we saw in the previous example an OpenSSL QUIC application always uses a
 nonblocking socket. However, despite this, the B<SSL> object still has blocking
 behaviour. When the B<SSL> 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 B<SSL>
 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 B<SSL>
 object is unable to read/write, for example updating a GUI or performing
 operations on some other connection or stream.

 We will see later in this tutorial how to change the B<SSL> object so that it
 has nonblocking behaviour. With a nonblocking B<SSL> object, functions such as
 L<SSL_read_ex(3)> or L<SSL_write_ex(3)> will return immediately with a non-fatal
 error if they are currently unable to read or write respectively.

 Since this page is building on the example developed on the
 L<ossl-guide-quic-client-block(7)> page we assume that you are familiar with it
 and we only explain how this example differs.

 =head2 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 B<SSL> object but we are currently unable to.
 In fact this is the whole point of using a nonblocking B<SSL> 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.

 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
 B<SSL> object is currently unable to write, then you cannot then attempt to
 write some other text when you retry the operation.

 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 B<SSL> object might have changed. We will call our
 function C<wait_for_activity()>.

     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's 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);
 }

 If you are familiar with how to write nonblocking applications in OpenSSL for
 TLS (see L<ossl-guide-tls-client-non-block(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 B<SSL> object and we get a "retry" response (B<SSL_ERROR_WANT_READ> or
 B<SSL_ERROR_WANT_WRITE>) 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
 L<SSL_read_ex(3)> or L<SSL_write_ex(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.

 To determine whether OpenSSL currently wants to read or write to the underlying
 socket for a QUIC application we must call the L<SSL_net_read_desired(3)> and
 L<SSL_net_write_desired(3)> functions.

 It is also important with QUIC that we periodically call an I/O function (or
 otherwise call the L<SSL_handle_events(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 B<SSL> object idle for a while
 while the application goes off to do other work. The L<SSL_get_event_timeout(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 L<SSL_handle_events(3)>).

 An alternative to using L<SSL_get_event_timeout(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 L<SSL_handle_events(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
 L</Creating the SSL_CTX and SSL objects> below for further details about this.

 In this example we are using the C<select> 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. C<select> waits for the state of the underlying
 socket(s) to become readable/writeable or until the timeout has expired before
 returning.

 =head2 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
 L<SSL_read_ex(3)> or L<SSL_write_ex(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).

 L<SSL_read_ex(3)> and L<SSL_write_ex(3)> will return 0 to indicate an error and
 L<SSL_read(3)> and L<SSL_write(3)> will return 0 or a negative value to indicate
 an error. L<SSL_shutdown(3)> will return a negative value to incidate an error.

 In the event of an error an application should call L<SSL_get_error(3)> to find
 out what type of error has occurred. If the error is non-fatal and can be
 retried then L<SSL_get_error(3)> will return B<SSL_ERROR_WANT_READ> or
 B<SSL_ERROR_WANT_WRITE> depending on whether OpenSSL wanted to read to or write
 from the stream but was unable to. Note that a call to L<SSL_read_ex(3)> or
 L<SSL_read(3)> can still generate B<SSL_ERROR_WANT_WRITE>. Similarly calls to
 L<SSL_write_ex(3)> or L<SSL_write(3)> might generate B<SSL_ERROR_WANT_READ>.

 Another type of non-fatal error that may occur is B<SSL_ERROR_ZERO_RETURN>. This
 indicates an EOF (End-Of-File) which can occur if you attempt to read data from
 an B<SSL> 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.

 Fatal errors that may occur are B<SSL_ERROR_SYSCALL> and B<SSL_ERROR_SSL>. 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 L<ERR_print_errors(3)> to print out details of errors that have
 occurred). You can also consult the return value of
 L<SSL_get_stream_read_state(3)> to determine whether the error is local to the
 stream, or whether the underlying connection has also failed. A return value
 of B<SSL_STREAM_STATE_RESET_REMOTE> tells you that the stream has been reset by
 the peer and B<SSL_STREAM_STATE_CONN_CLOSED> tells you that the underlying
 connection has closed.

 In our demo application we will write a function to handle these errors from
 OpenSSL I/O functions:

     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\n");
                 /*
                  * The stream has been reset but the connection is still
                  * healthy.
                  */
                 break;

             case SSL_STREAM_STATE_CONN_CLOSED:
                 printf("Connection closed\n");
                 /* Connection is already closed. */
                 break;

             default:
                 printf("Unknown stream failure\n");
                 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\n",
                     X509_verify_cert_error_string(SSL_get_verify_result(ssl)));
             return -1;

         default:
             return -1;
         }
     }

 This function takes as arguments the B<SSL> 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 C<wait_for_activity()> 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.

 =head2 Creating the SSL_CTX and SSL objects

 In order to connect to a server we must create B<SSL_CTX> and B<SSL> objects for
 this. Most of the steps to do this are the same as for a blocking client and are
 explained on the L<ossl-guide-quic-client-block(7)> page. We won't repeat that
 information here.

 One key difference is that we must put the B<SSL> object into nonblocking mode
 (the default is blocking mode). To do that we use the
 L<SSL_set_blocking_mode(3)> function:

     /*
      * 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\n");
         goto end;
     }

 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
 L<SSL_handle_events(3)> (or alternatively any I/O function) is called on the
 connection B<SSL> object periodically to maintain the connection in a healthy
 state. See L</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 B<SSL> 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 L<OSSL_QUIC_client_thread_method(3)> when we construct the
 B<SSL_CTX> as shown below:

     ctx = SSL_CTX_new(OSSL_QUIC_client_thread_method());
     if (ctx == NULL) {
         printf("Failed to create the SSL_CTX\n");
         goto end;
     }

 =head2 Performing the handshake

 As in the demo for a blocking QUIC client we use the L<SSL_connect(3)> function
 to perform the handshake with the server. Since we are using a nonblocking
 B<SSL> 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 L<SSL_connect(3)> call at a
 later time. In this demo we do this in a loop:

     /* 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\n");
         goto end; /* Cannot retry: error */
     }

 We continually call L<SSL_connect(3)> until it gives us a success response.
 Otherwise we use the C<handle_io_failure()> 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.

 =head2 Sending and receiving data

 As with the blocking QUIC client demo we use the L<SSL_write_ex(3)> function to
 send data to the server. As with L<SSL_connect(3)> above, because we are using
 a nonblocking B<SSL> object, this call could fail with a non-fatal error. In
 that case we should retry exactly the same L<SSL_write_ex(3)> call again. Note
 that the parameters must be I<exactly> 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
 (B<SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER>) 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 L<SSL_CTX_set_mode(3)> for further
 details. As in the TLS tutorials (L<ossl-guide-tls-client-block(7)>) we write
 the request in three chunks.

 First, we write the entire request to the stream. We also must make sure to
 signal to the server that we have finished writing. This can be done by passing
 the SSL_WRITE_FLAG_CONCLUDE flag to L<SSL_write_ex2(3)> or by calling
 L<SSL_stream_conclude(3)>. Since the first way is more efficient, we choose to
 do that.

     /* 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\n");
         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\n");
         goto end; /* Cannot retry: error */
     }
     while (!SSL_write_ex2(ssl, request_end, strlen(request_end),
            SSL_WRITE_FLAG_CONCLUDE, &written)) {
         if (handle_io_failure(ssl, 0) == 1)
             continue; /* Retry */
         printf("Failed to write end of HTTP request\n");
         goto end; /* Cannot retry: error */
     }

 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.

 Reading a response back from the server is similar:

     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\n");
                 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're going to print it to stdout anyway.
          */
         if (!eof)
             fwrite(buf, 1, readbytes, stdout);
     } while (!eof);
     /* In case the response didn't finish with a newline we add one now */
     printf("\n");

 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.

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

 =head2 Shutting down the connection

 As in the QUIC blocking example we must shutdown the connection when we are
 finished with it.

 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
 L<SSL_shutdown(3)>.

 Since our application is initiating the shutdown then we might expect to see
 L<SSL_shutdown(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 B<SSL> object we might expect to
 have to retry this operation several times. If L<SSL_shutdown(3)> returns a
 negative result then we must call L<SSL_get_error(3)> to work out what to do
 next. We use our handle_io_failure() function that we developed earlier for
 this:

     /*
      * 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 */
     }

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

 =head1 FURTHER READING

 See L<ossl-guide-quic-client-block(7)> to read a tutorial on how to write a
 blocking QUIC client. See L<ossl-guide-quic-multi-stream(7)> to see how to write
 a multi-stream QUIC client.

 =head1 SEE ALSO

 L<ossl-guide-introduction(7)>, L<ossl-guide-libraries-introduction(7)>,
 L<ossl-guide-libssl-introduction(7)>, L<ossl-guide-quic-introduction(7)>,
 L<ossl-guide-quic-client-block(7)>, L<ossl-guide-quic-multi-stream(7)>

 =head1 COPYRIGHT

 Copyright 2023-2025 The OpenSSL Project Authors. All Rights Reserved.

 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
 L<https://www.openssl.org/source/license.html>.

 =cut
	=pod

	=begin comment

	NB: Changes to the source code samples in this file should also be reflected in
	demos/guide/quic-client-non-block.c

	=end comment

	=head1 NAME

	ossl-guide-quic-client-non-block
	- OpenSSL Guide: Writing a simple nonblocking QUIC client

	=head1 SIMPLE NONBLOCKING QUIC CLIENT EXAMPLE

	This page will build on the example developed on the
	L<ossl-guide-quic-client-block(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.

	The complete source code for this example nonblocking QUIC client is available
	in the B<demos/guide> directory of the OpenSSL source distribution in the file
	B<quic-client-non-block.c>. It is also available online at
	L<https://github.com/openssl/openssl/blob/master/demos/guide/quic-client-non-block.c>.

	As we saw in the previous example an OpenSSL QUIC application always uses a
	nonblocking socket. However, despite this, the B<SSL> object still has blocking
	behaviour. When the B<SSL> 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 B<SSL>
	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 B<SSL>
	object is unable to read/write, for example updating a GUI or performing
	operations on some other connection or stream.

	We will see later in this tutorial how to change the B<SSL> object so that it
	has nonblocking behaviour. With a nonblocking B<SSL> object, functions such as
	L<SSL_read_ex(3)> or L<SSL_write_ex(3)> will return immediately with a non-fatal
	error if they are currently unable to read or write respectively.

	Since this page is building on the example developed on the
	L<ossl-guide-quic-client-block(7)> page we assume that you are familiar with it
	and we only explain how this example differs.

	=head2 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 B<SSL> object but we are currently unable to.
	In fact this is the whole point of using a nonblocking B<SSL> 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.

	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
	B<SSL> object is currently unable to write, then you cannot then attempt to
	write some other text when you retry the operation.

	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 B<SSL> object might have changed. We will call our
	function C<wait_for_activity()>.

	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's 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);
	}

	If you are familiar with how to write nonblocking applications in OpenSSL for
	TLS (see L<ossl-guide-tls-client-non-block(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 B<SSL> object and we get a "retry" response (B<SSL_ERROR_WANT_READ> or
	B<SSL_ERROR_WANT_WRITE>) 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
	L<SSL_read_ex(3)> or L<SSL_write_ex(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.

	To determine whether OpenSSL currently wants to read or write to the underlying
	socket for a QUIC application we must call the L<SSL_net_read_desired(3)> and
	L<SSL_net_write_desired(3)> functions.

	It is also important with QUIC that we periodically call an I/O function (or
	otherwise call the L<SSL_handle_events(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 B<SSL> object idle for a while
	while the application goes off to do other work. The L<SSL_get_event_timeout(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 L<SSL_handle_events(3)>).

	An alternative to using L<SSL_get_event_timeout(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 L<SSL_handle_events(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
	L</Creating the SSL_CTX and SSL objects> below for further details about this.

	In this example we are using the C<select> 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. C<select> waits for the state of the underlying
	socket(s) to become readable/writeable or until the timeout has expired before
	returning.

	=head2 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
	L<SSL_read_ex(3)> or L<SSL_write_ex(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).

	L<SSL_read_ex(3)> and L<SSL_write_ex(3)> will return 0 to indicate an error and
	L<SSL_read(3)> and L<SSL_write(3)> will return 0 or a negative value to indicate
	an error. L<SSL_shutdown(3)> will return a negative value to incidate an error.

	In the event of an error an application should call L<SSL_get_error(3)> to find
	out what type of error has occurred. If the error is non-fatal and can be
	retried then L<SSL_get_error(3)> will return B<SSL_ERROR_WANT_READ> or
	B<SSL_ERROR_WANT_WRITE> depending on whether OpenSSL wanted to read to or write
	from the stream but was unable to. Note that a call to L<SSL_read_ex(3)> or
	L<SSL_read(3)> can still generate B<SSL_ERROR_WANT_WRITE>. Similarly calls to
	L<SSL_write_ex(3)> or L<SSL_write(3)> might generate B<SSL_ERROR_WANT_READ>.

	Another type of non-fatal error that may occur is B<SSL_ERROR_ZERO_RETURN>. This
	indicates an EOF (End-Of-File) which can occur if you attempt to read data from
	an B<SSL> 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.

	Fatal errors that may occur are B<SSL_ERROR_SYSCALL> and B<SSL_ERROR_SSL>. 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 L<ERR_print_errors(3)> to print out details of errors that have
	occurred). You can also consult the return value of
	L<SSL_get_stream_read_state(3)> to determine whether the error is local to the
	stream, or whether the underlying connection has also failed. A return value
	of B<SSL_STREAM_STATE_RESET_REMOTE> tells you that the stream has been reset by
	the peer and B<SSL_STREAM_STATE_CONN_CLOSED> tells you that the underlying
	connection has closed.

	In our demo application we will write a function to handle these errors from
	OpenSSL I/O functions:

	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\n");
	/*
	* The stream has been reset but the connection is still
	* healthy.
	*/
	break;

	case SSL_STREAM_STATE_CONN_CLOSED:
	printf("Connection closed\n");
	/* Connection is already closed. */
	break;

	default:
	printf("Unknown stream failure\n");
	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\n",
	X509_verify_cert_error_string(SSL_get_verify_result(ssl)));
	return -1;

	default:
	return -1;
	}
	}

	This function takes as arguments the B<SSL> 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 C<wait_for_activity()> 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.

	=head2 Creating the SSL_CTX and SSL objects

	In order to connect to a server we must create B<SSL_CTX> and B<SSL> objects for
	this. Most of the steps to do this are the same as for a blocking client and are
	explained on the L<ossl-guide-quic-client-block(7)> page. We won't repeat that
	information here.

	One key difference is that we must put the B<SSL> object into nonblocking mode
	(the default is blocking mode). To do that we use the
	L<SSL_set_blocking_mode(3)> function:

	/*
	* 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\n");
	goto end;
	}

	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
	L<SSL_handle_events(3)> (or alternatively any I/O function) is called on the
	connection B<SSL> object periodically to maintain the connection in a healthy
	state. See L</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 B<SSL> 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 L<OSSL_QUIC_client_thread_method(3)> when we construct the
	B<SSL_CTX> as shown below:

	ctx = SSL_CTX_new(OSSL_QUIC_client_thread_method());
	if (ctx == NULL) {
	printf("Failed to create the SSL_CTX\n");
	goto end;
	}

	=head2 Performing the handshake

	As in the demo for a blocking QUIC client we use the L<SSL_connect(3)> function
	to perform the handshake with the server. Since we are using a nonblocking
	B<SSL> 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 L<SSL_connect(3)> call at a
	later time. In this demo we do this in a loop:

	/* 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\n");
	goto end; /* Cannot retry: error */
	}

	We continually call L<SSL_connect(3)> until it gives us a success response.
	Otherwise we use the C<handle_io_failure()> 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.

	=head2 Sending and receiving data

	As with the blocking QUIC client demo we use the L<SSL_write_ex(3)> function to
	send data to the server. As with L<SSL_connect(3)> above, because we are using
	a nonblocking B<SSL> object, this call could fail with a non-fatal error. In
	that case we should retry exactly the same L<SSL_write_ex(3)> call again. Note
	that the parameters must be I<exactly> 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
	(B<SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER>) 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 L<SSL_CTX_set_mode(3)> for further
	details. As in the TLS tutorials (L<ossl-guide-tls-client-block(7)>) we write
	the request in three chunks.

	First, we write the entire request to the stream. We also must make sure to
	signal to the server that we have finished writing. This can be done by passing
	the SSL_WRITE_FLAG_CONCLUDE flag to L<SSL_write_ex2(3)> or by calling
	L<SSL_stream_conclude(3)>. Since the first way is more efficient, we choose to
	do that.

	/* 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\n");
	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\n");
	goto end; /* Cannot retry: error */
	}
	while (!SSL_write_ex2(ssl, request_end, strlen(request_end),
	SSL_WRITE_FLAG_CONCLUDE, &written)) {
	if (handle_io_failure(ssl, 0) == 1)
	continue; /* Retry */
	printf("Failed to write end of HTTP request\n");
	goto end; /* Cannot retry: error */
	}

	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.

	Reading a response back from the server is similar:

	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\n");
	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're going to print it to stdout anyway.
	*/
	if (!eof)
	fwrite(buf, 1, readbytes, stdout);
	} while (!eof);
	/* In case the response didn't finish with a newline we add one now */
	printf("\n");

	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.

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

	=head2 Shutting down the connection

	As in the QUIC blocking example we must shutdown the connection when we are
	finished with it.

	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
	L<SSL_shutdown(3)>.

	Since our application is initiating the shutdown then we might expect to see
	L<SSL_shutdown(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 B<SSL> object we might expect to
	have to retry this operation several times. If L<SSL_shutdown(3)> returns a
	negative result then we must call L<SSL_get_error(3)> to work out what to do
	next. We use our handle_io_failure() function that we developed earlier for
	this:

	/*
	* 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 */
	}

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

	=head1 FURTHER READING

	See L<ossl-guide-quic-client-block(7)> to read a tutorial on how to write a
	blocking QUIC client. See L<ossl-guide-quic-multi-stream(7)> to see how to write
	a multi-stream QUIC client.

	=head1 SEE ALSO

	L<ossl-guide-introduction(7)>, L<ossl-guide-libraries-introduction(7)>,
	L<ossl-guide-libssl-introduction(7)>, L<ossl-guide-quic-introduction(7)>,
	L<ossl-guide-quic-client-block(7)>, L<ossl-guide-quic-multi-stream(7)>

	=head1 COPYRIGHT

	Copyright 2023-2025 The OpenSSL Project Authors. All Rights Reserved.

	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
	L<https://www.openssl.org/source/license.html>.

	=cut