OSSL-GUIDE-T...ENT-NON-BLOCK(7SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

💖 NAME 💖

okay bestie, welcome to ossl-guide-tls-client-non-block — the OpenSSL Guide page about Writing a simple nonblocking TLS client. Its header calls it OSSL-GUIDE-T...ENT-NON-BLOCK(7SSL), so like, that's the whole name. And it's an OpenSSL thing. Periodt. ✨

🌈 SIMPLE NONBLOCKING TLS CLIENT EXAMPLE 🌈

This page is a glow-up 💅 of the example we already built on the ossl-guide-tls-client-block(7) page — you know, the one showing how to write a simple blocking TLS client. Here we're taking that demo code and amending it so it supports a nonblocking socket. Same girl, new outfit.

The complete source code for this example nonblocking TLS client lives in the demos/guide directory of the OpenSSL source distribution, in the file tls-client-non-block.c. It's also up online at https://github.com/openssl/openssl/blob/master/demos/guide/tls-client-non-block.c.

So, recap on the lore from the previous example: a blocking socket is one that waits (blocks) until data is available to read if you try to read from it when there's no data yet. Same energy when writing — if the socket can't write right now, it just sits there. And ngl, that's kinda convenient, because you don't have to worry about what to do in those cases; the code just stops until it can keep going. But lowkey, in so many cases you do not want that behaviour. Instead of stopping and waiting, your app might need to go do other tasks while the socket is unable to read/write — like updating a GUI, or doing operations on some other socket. Main character multitasking. 👑

With a nonblocking socket, attempting to read or write to a socket that currently can't read or write will return immediately with a non-fatal error. And even though OpenSSL is the one doing the reading/writing to the socket, this nonblocking behaviour gets propagated all the way up to your application, so OpenSSL I/O functions such as SSL_read_ex(3) or SSL_write_ex(3) will not block. 🦋

And because this page is building on the example from ossl-guide-tls-client-block(7), we're assuming you're already familiar with it, and we're only explaining how this example differs. iykyk.

🎀 Setting the socket to be nonblocking 🎀

First step, bestie: set the socket into nonblocking mode. A socket is blocking by default. The exact details of how to do this can differ from one platform to another. BUT fortunately, OpenSSL offers a portable function that does it for you:

/* Set to nonblocking mode */
if (!BIO_socket_nbio(sock, 1)) {
    sock = -1;
    continue;
}

You do not have to use OpenSSL's function for this, tho. You can of course directly call whatever functions your Operating System provides for this purpose on your platform. Slay whatever way you like. ✨

💅 Performing work while waiting for the socket 💅

In a nonblocking application you're gonna need work to perform in the event that you want to read or write to the socket but you're currently unable to. Honestly? That is the whole point of using a nonblocking socket — giving the application the opportunity to go do something else.

But whatever it is your app 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 that in the event that the state of the underlying socket has actually changed (like, it became readable where it wasn't before) — but it doesn't have to be that way. It can retry at any time.

⚠️ Real talk, and this part matters: it is super 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 socket is currently unable to write, then you cannot then attempt to write some other text when you retry the operation. No switching up mid-retry. 🚫

In this demo application we're gonna create a helper function which simulates doing other work. In fact, for the sake of simplicity, it'll do nothing except wait for the state of the socket to change.

We call our function wait_for_activity() because all it does is wait until the underlying socket has become readable or writeable when it wasn't before. That's it, that's the function:

static void wait_for_activity(SSL *ssl, int write)
{
    fd_set fds;
    int width, sock;

    /* Get hold of the underlying file descriptor for the socket */
    sock = SSL_get_fd(ssl);

    FD_ZERO(&fds);
    FD_SET(sock, &fds);
    width = sock + 1;

    /*
     * 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 add a 100ms timeout
     * in the last parameter to "select" below. Then, when select returns,
     * you check if it did so because of activity on the file descriptors or
     * because of the timeout. If it is due to the timeout then update the
     * GUI and then restart the "select".
     */
    if (write)
        select(width, NULL, &fds, NULL, NULL);
    else
        select(width, &fds, NULL, NULL, NULL);
}

In this example we're using the "select" function because it's very simple to use and it's available on most Operating Systems. But 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 before returning. It also supports a "timeout" (as do most other similar functions), so in your own applications you can make use of that to periodically wake up and perform work while you're waiting for the socket state to change. But we don't use that timeout capability in this example, for the sake of simplicity. 🫶

🌸 Handling errors from OpenSSL I/O functions 🌸

An application that uses a nonblocking socket 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 example, because the underlying connection has failed) or non-fatal (for example, because we're trying to read from the underlying socket but the data has not yet arrived from the peer).

Quick receipts on who returns what: 📝

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 from or write to the socket but was unable to. And bestie, here's the twist — a call to SSL_read_ex(3) or SSL_read(3) can still generate SSL_ERROR_WANT_WRITE, because OpenSSL may need to write protocol messages (such as to update cryptographic keys) even if the application is only trying to read data. Similarly, calls to SSL_write_ex(3) or SSL_write(3) might generate SSL_ERROR_WANT_READ. Not me pointing out that the read function can want to write, but here we are. 💀

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 it. In this case you may still want to write data to the connection, 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 underlying connection has failed.

🚨 You should not attempt to shut it down with SSL_shutdown(3). Do not do it.

SSL_ERROR_SYSCALL indicates that OpenSSL attempted to make a syscall that failed. You can consult errno for further details. SSL_ERROR_SSL indicates that some OpenSSL error occurred. 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).

In our demo application we'll 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:
        /* Temporary failure. Wait until we can read and try again */
        wait_for_activity(ssl, 0);
        return 1;

    case SSL_ERROR_WANT_WRITE:
        /* Temporary failure. Wait until we can write and try again */
        wait_for_activity(ssl, 1);
        return 1;

    case SSL_ERROR_ZERO_RETURN:
        /* EOF */
        return 0;

    case SSL_ERROR_SYSCALL:
        return -1;

    case SSL_ERROR_SSL:
        /*
        * 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, plus 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 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. Clean, simple, iconic. ✨

🦋 Creating the SSL_CTX and SSL objects 🦋

In order to connect to a server we must create SSL_CTX and SSL objects for this. The steps to do this are the same as for a blocking client and are explained on the ossl-guide-tls-client-block(7) page. We won't repeat that information here. Go read that one, bestie, we're not retyping it. 🙈

👑 Performing the handshake 👑

As in the demo for a blocking TLS client, we use the SSL_connect(3) function to perform the TLS handshake with the server. Since we're using a nonblocking socket, 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. 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 */
}

okay bestie so we keep calling SSL_connect(3) over and over until it finally hits us with a 1 — that's the ✨success✨ signal. Any other result and we hand it straight to our lil helper handle_io_failure() (the one we built earlier, she's an icon) and let her decide the next move. One thing tho: at this stage we do NOT expect an EOF to show up — if we see one here it gets treated exactly like a fatal error, no mercy. 💀

🌸 Sending and receiving data 🌸

Just like in the blocking TLS client demo, we use SSL_write_ex(3) to yeet our data at the server. And just like SSL_connect(3) up there, since our socket is nonblocking, this call can bounce back with a non-fatal error. When that happens? We retry the exact same SSL_write_ex(3) call again.

🫶 Listen up: the parameters have to be EXACTLY the same — same pointer to the buffer, same length. Do not try to sneak different data in on a retry. That's not it.

There is an optional mode, SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER, which tells OpenSSL it's fine for the buffer being written to move between retries. But even with that on, you still have to retry exactly the same data — the buffer holding it can just change location. See SSL_CTX_set_mode(3) for the whole tea. ☕

And like in the blocking TLS client tutorial (ossl-guide-tls-client-block(7)), we write the request out in three chunks:

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

On a write, we're not expecting an EOF response, so that case gets handled the same way as a fatal error. no exceptions babe. 🙈

Reading the response back from the server is basically the same vibe:

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 big glow-up this time? Receiving an EOF while reading data from the server is totally valid. That's just the server closing the connection after it's sent everything in its response. graceful queen behavior 👑

In this demo we just print out literally everything we got back from the server. We keep looping and looping until we either hit a fatal error or catch that EOF (which means a graceful finish 🎀).

💅 Shutting down the connection 💅

Same as the TLS blocking example — when we're done with the connection, we must shut her down.

If our app was the one kicking off the shutdown, we'd expect SSL_shutdown(3) to give us a 0, and then we'd keep calling it until we got a 1 (which means the shutdown finished successfully, slay). But in this particular example we don't expect SSL_shutdown() to return 0, because we already got EOF from the server — meaning it already shut down. So we just keep calling until SSL_shutdown() returns 1.

And since our socket is nonblocking, expect to retry this a few times. If SSL_shutdown(3) returns something negative, we must call SSL_get_error(3) to figure out what's next. We use that handle_io_failure() function we cooked up earlier for exactly this:

/*
 * The peer already shutdown gracefully (we know this because of the
 * SSL_ERROR_ZERO_RETURN (i.e. EOF) above). We should do the same back.
 */
while ((ret = SSL_shutdown(ssl)) != 1) {
    if (ret < 0 && handle_io_failure(ssl, ret) == 1)
        continue; /* Retry */
    /*
     * ret == 0 is unexpected here because that means "we've sent a
     * close_notify and we're waiting for one back". But we already know
     * we got one from the peer because of the SSL_ERROR_ZERO_RETURN
     * (i.e. EOF) above.
     */
    printf("Error shutting down\n");
    goto end; /* Cannot retry: error */
}
😭 reminder: ret == 0 is unexpected here, because 0 means "we sent a close_notify and we're waiting for one back" — but we already know we got one from the peer, thanks to that SSL_ERROR_ZERO_RETURN (i.e. EOF) from earlier.

🧚 Final clean up 🧚

Like in the blocking TLS client example: once we're finished with the connection, we must free it. The steps here are the exact same as the blocking example, so we're not repeating them, periodt. 💖

🌈 FURTHER READING 🌈

👑 SEE ALSO 👑

Copyright 2023 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>.

and that's the whole page bestie!! 🦋 this was version 4.0.3, dated 2026-09-29 — go forth and nonblock responsibly, you absolute legend 💅⭐

📦 where this page comes from