OSSL-GUIDE-QU...ENT-NON-BLOCK(7SSL) OpenSSL OSSL-GUIDE-QU...ENT-NON-BLOCK(7SSL)
NAME
ossl-guide-quic-client-non-block - OpenSSL Guide: Writing a simple
nonblocking QUIC client
SIMPLE NONBLOCKING QUIC CLIENT EXAMPLE
This page will build on the example developed on the
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 demos/guide directory of the OpenSSL source
distribution in the file quic-client-non-block.c. It is also available
online at
<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 SSL object still
has blocking behaviour. When the 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 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 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 SSL object so that
it has nonblocking behaviour. With a nonblocking SSL object, functions
such as SSL_read_ex(3) or 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
ossl-guide-quic-client-block(7) page we assume that you are familiar
with it and we only explain how this example differs.
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 SSL object but we are currently
unable to. In fact this is the whole point of using a nonblocking 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 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 SSL object might
have changed. We will call our function 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 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 SSL object and we get a "retry"
response (SSL_ERROR_WANT_READ or 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
SSL_read_ex(3) or 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
SSL_net_read_desired(3) and SSL_net_write_desired(3) functions.
It is also important with QUIC that we periodically call an I/O function
(or otherwise call the 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 SSL object
idle for a while while the application goes off to do other work. The
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
SSL_handle_events(3)).
An alternative to using 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 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 "Creating the SSL_CTX and SSL objects" below for further
details about this.
In this example we are using the "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. "select" waits for the
state of the underlying socket(s) to become readable/writeable or until
the timeout has expired before returning.
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 SSL_read_ex(3) or 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).
SSL_read_ex(3) and SSL_write_ex(3) will return 0 to indicate an error
and SSL_read(3) and SSL_write(3) will return 0 or a negative value to
indicate an error. SSL_shutdown(3) will return a negative value to
incidate an error.
In the event of an error an application should call SSL_get_error(3) to
find out what type of error has occurred. If the error is non-fatal and
can be retried then SSL_get_error(3) will return SSL_ERROR_WANT_READ or
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
SSL_read_ex(3) or SSL_read(3) can still generate SSL_ERROR_WANT_WRITE.
Similarly calls to SSL_write_ex(3) or SSL_write(3) might generate
SSL_ERROR_WANT_READ.
Another type of non-fatal error that may occur is SSL_ERROR_ZERO_RETURN.
This indicates an EOF (End-Of-File) which can occur if you attempt to
read data from an 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 SSL_ERROR_SYSCALL and 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 ERR_print_errors(3) to
print out details of errors that have occurred). You can also consult
the return value of 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 SSL_STREAM_STATE_RESET_REMOTE tells
you that the stream has been reset by the peer and
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 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 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.
Creating the SSL_CTX and SSL objects
In order to connect to a server we must create SSL_CTX and SSL objects
for this. Most of the steps to do this are the same as for a blocking
client and are explained on the ossl-guide-quic-client-block(7) page. We
won't repeat that information here.
One key difference is that we must put the SSL object into nonblocking
mode (the default is blocking mode). To do that we use the
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 SSL_handle_events(3) (or alternatively any I/O function)
is called on the connection SSL 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 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 OSSL_QUIC_client_thread_method(3) when we construct the
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;
}
Performing the handshake
As in the demo for a blocking QUIC client we use the SSL_connect(3)
function to perform the handshake with the server. Since we are using a
nonblocking 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
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 SSL_connect(3) until it gives us a success response.
Otherwise we use the 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.
Sending and receiving data
As with the blocking QUIC client demo we use the SSL_write_ex(3)
function to send data to the server. As with SSL_connect(3) above,
because we are using a nonblocking SSL object, this call could fail with
a non-fatal error. In that case we should retry exactly the same
SSL_write_ex(3) call again. Note that the parameters must be 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 (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 SSL_CTX_set_mode(3) for further details. As in the TLS
tutorials (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 SSL_write_ex2(3) or by
calling 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).
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 SSL_shutdown(3).
Since our application is initiating the shutdown then we might expect to
see 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 SSL object we might expect to have to retry this operation
several times. If SSL_shutdown(3) returns a negative result then we must
call 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 */
}
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.
FURTHER READING
See ossl-guide-quic-client-block(7) to read a tutorial on how to write a
blocking QUIC client. See ossl-guide-quic-multi-stream(7) to see how to
write a multi-stream QUIC client.
SEE ALSO
ossl-guide-introduction(7), ossl-guide-libraries-introduction(7),
ossl-guide-libssl-introduction(7), ossl-guide-quic-introduction(7),
ossl-guide-quic-client-block(7), ossl-guide-quic-multi-stream(7)
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
<https://www.openssl.org/source/license.html>.
3.5.4 2025-09-3OSSL-GUIDE-QU...ENT-NON-BLOCK(7SSL)
Generated by dwww version 1.16 on Tue Dec 16 05:08:12 CET 2025.