OSSL-GUIDE-Q...NT-NON-BLOCK(7ossl)
okay so you’ve opened ossl-guide-quic-client-non-block(7ossl) — it’s an OpenSSL guide page, and it’s literally all about writing a simple nonblocking QUIC client. bestie, we’re taking the blocking demo from ossl-guide-quic-client-block(7) and giving it nonblocking main character energy ✨💅
🌸 NAME 🌸
ossl-guide-quic-client-non-block — OpenSSL Guide: Writing a simple nonblocking QUIC client 🦋
🌈 SIMPLE NONBLOCKING QUIC CLIENT EXAMPLE 🌈
This page builds on the example from ossl-guide-quic-client-block(7), which shows how to write a simple blocking QUIC client. Here, we’re amending that demo code so it supports nonblocking functionality. slay.
The complete source code for this example nonblocking QUIC client lives in the demos/guide directory of the OpenSSL source distribution, in the file quic-client-non-block.c. It’s 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. But — plot twist 🔥 — despite that, the SSL object still has blocking behaviour. When the SSL object has blocking behaviour, that means it waits (blocks) until data is available to read if you try to read from it when there’s no data yet. Same vibe when writing: it waits if the SSL object is currently unable to write at that moment. This can simplify development, because you don’t have to worry about what to do in those cases — execution just stops until it can continue. iconic for easy code, honestly.
But in many cases you do not want this behaviour. Instead of stopping and waiting, your application may need to go 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. very “I have other plans” of it 💅
We’ll see later in this tutorial how to change the SSL object so 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’re currently unable to read or write respectively. no waiting around, no drama.
Since this page is building on the example developed on the ossl-guide-quic-client-block(7) page, we assume you’re familiar with it, and we only explain how this example differs. iykyk 🧚
🦋 Performing work while waiting for the socket 🦋
In a nonblocking application, you’ll need work to perform in the event that we want to read or write to the SSL object but we’re currently unable to. In fact, that’s the whole point of using a nonblocking SSL object: giving the application the opportunity to do something else. Whatever it is the application has to do, it must also be prepared to come back and retry the operation 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 doesn’t have to be the case. It can retry at any time. lowkey flexible.
⚠️ Important: 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 theSSLobject is currently unable to write, then you cannot then attempt to write some other text when you retry the operation. periodt.
In this demo application we’ll create a helper function which simulates doing other work. 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’ll 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’re familiar with how to write nonblocking applications in OpenSSL for TLS (see ossl-guide-tls-client-non-block(7)), then you should note there’s 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’s 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. kinda iconic, kinda confusing, we love her 💀
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. those are the vibe-check functions 👑
It’s 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’re 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’re 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. old school but still slaying 🎀
💅 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’re trying to read from the stream but no data has arrived from the peer yet 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 indicate an error. noted, bestie 🫡
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. plot twist, but make it networking 🔥
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. bittersweet 💔
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;
}
}okay so bestie, this function takes two things as arguments 💅 — the SSL object that represents the connection, and the return code from the I/O function that just failed. And here's the tea: if the failure is non-fatal, it waits until a retry of the I/O operation might actually succeed (that's the wait_for_activity() function we built in the previous section, she's doing her thing 🧚).
What does it return? So glad you asked:
1on a non-fatal error (except EOF — she's special, keep reading)0when it's EOF-1if a fatal error happened, no cap 💀
🎀 Creating the SSL_CTX and SSL objects 🎀
So to connect to a server we need to make SSL_CTX and SSL objects — standard, we been knew. Most of the steps are literally the same as for a blocking client, and they're fully explained over on the ossl-guide-quic-client-block(7) page. Not repeating all that here, go read it, I'll wait 🫶
The one key difference? We gotta put the SSL object into nonblocking mode (default is blocking mode, lowkey clingy of it). 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;
}Now, the demo app we're building here doesn't use it, but highkey it's possible to use "thread assisted mode" when you're developing QUIC applications. Here's why that matters: normally, when writing an OpenSSL QUIC application, it's important that SSL_handle_events(3) (or alternatively any I/O function) gets called on the connection SSL object periodically, so the connection stays in a healthy state. More chat about that under "Performing work while waiting for the socket" — go peek, it's worth it ✨
This is especially important to keep in mind when you're writing a nonblocking QUIC app, because it's super common to leave the SSL connection object idle for a while in nonblocking mode. And by using "thread assisted mode", OpenSSL creates a separate thread to do it all automatically for you, which means you — the application developer — don't have to handle that aspect at all. Main character energy honestly 👑
To do this we must use OSSL_QUIC_client_thread_method(3) when we construct the SSL_CTX, like so:
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 🔥
Same as in the blocking QUIC client demo — we use SSL_connect(3) to do the handshake with the server. But since we're rocking a nonblocking SSL object, it's very likely that calls to this function will fail with a non-fatal error while we're waiting for the server to respond to our handshake messages. Totally normal, don't panic 🩷
When that happens we have to retry the exact same SSL_connect(3) call later. In this demo we do it 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 keep calling SSL_connect(3) until it hands us that sweet success response. Otherwise we lean on the handle_io_failure() function we made earlier to figure out what to do next. And ngl — we do not expect an EOF to happen at this stage, so if we get one, it's treated exactly like a fatal error. Rude, but that's the rule 💀
🌸 Sending and receiving data 🌸
Same as the blocking QUIC client demo, we use SSL_write_ex(3) to send data to the server. And same as with SSL_connect(3) above, because our SSL object is nonblocking, this call could fail with a non-fatal error. In that case we retry exactly the same SSL_write_ex(3) call again. Not similar, not "close enough" — exactly the same 👏
⚠️ Warning bestie: 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. There is an optional mode —SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER— which configures OpenSSL to allow the buffer being written to change from one retry to the next. BUT even then, you must still retry exactly the same data, even though the buffer that contains that data may change location. SeeSSL_CTX_set_mode(3)for the full details.
And 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 have to make sure we signal to the server that we're done writing. Two ways: pass the SSL_WRITE_FLAG_CONCLUDE flag to SSL_write_ex2(3), or call SSL_stream_conclude(3). The first way is more efficient, so that's the one we're choosing. Slay 💅
/* 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 the same way as a fatal error. Periodt.
Reading a response back from the server is similar — honestly, it's giving sibling energy:
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: it's totally valid for us to receive an EOF response when trying to read data from the server 🦋 That's just what happens when the server closes down the connection after sending all the data in its response. Bye bestie 👋
In this demo we just print out all the data we got back in the response from the server. And we keep going around the loop until we either hit a fatal error, or we receive an EOF (which means a graceful finish, iconic ✨).
💜 Shutting down the connection 💜
As in the QUIC blocking example, we gotta shut the connection down when we're done with it.
And listen — even though we received EOF on the stream we were reading from above, that tells us nothing about the state of the underlying connection. Nothing! Zero info! So our demo app initiates the connection shutdown process via SSL_shutdown(3).
Since our application is the one initiating the shutdown, we might expect SSL_shutdown(3) to give us a return value of 0 — and then we should keep calling it until we get a return value of 1 (which means the shutdown completed successfully, and we can celebrate 🎉). And because we're using a nonblocking SSL object, we might have to retry this operation several times. It's giving "loading screen" ngl.
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 exactly 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're not repeating it here. Go check that page, it's all there, I promise 🫶
🦋 FURTHER READING 🦋
okay so if you want more after this — and honestly same, bestie, this stuff is addictive — there's literally more where that came from:
- want the chill, wait-for-it version? go read
ossl-guide-quic-client-block(7)— it's a whole tutorial on writing a blocking QUIC client, no event loops, no stress 💅 - feeling ambitious and want all the streams at once?
ossl-guide-quic-multi-stream(7)shows you how to write a multi-stream QUIC client. main character energy fr fr 🌈
👑 SEE ALSO 👑
the full squad, in order, no cap:
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)
like, that's the whole reading list. collect them all 🎀
🎀 COPYRIGHT 🎀
okay legal moment, but make it cute — this is the part where you don't skip, bestie, because rules are rules 💖
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. 🫶
ngl, "you may not use this file except in compliance with the License" is the legal equivalent of "don't test me" — so like, actually read the license, okay? 🙈
and that's a wrap on this guide!! you made it to the very end, which is honestly iconic of you ✨ go forth and build your non-blocking QUIC client, you absolute legend 🧚♀️ slay 💜
this page is from OpenSSL 3.5.0, dated 2026-09-25 — so if you're reading this way later, hi, hope the QUIC still slaps 🦋
📦 where this page comes from
- opensuse-leap 16.0: openssl-3 3.5.0-160000.11.1 · Apache-2.0
- opensuse-leap 16.0: openssl-3 3.5.0-160000.11.1 · Apache-2.0
- opensuse-leap 16.0: openssl-3 3.5.0-160000.11.1 · Apache-2.0
- opensuse-leap 16.0: openssl-3 3.5.0-160000.11.1 · Apache-2.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms