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

📦
version 3.5.9 · 8 versions
, in alpine 3.23, alpine 3.24

🌸 NAME 🌸

ossl-guide-tls-client-non-block — the OpenSSL Guide's guide to writing a simple nonblocking TLS client, brought to you by the 7ossl girlies 💅

💖 SIMPLE NONBLOCKING TLS CLIENT EXAMPLE 💖

okay so bestie, this page is a glow-up of the example from the ossl-guide-tls-client-block(7) page — that one showed you how to write a simple blocking TLS client. here we're taking that exact demo code and giving it a personality transplant so it supports a nonblocking socket ✨

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 online at <https://github.com/openssl/openssl/blob/master/demos/guide/tls-client-non-block.c> 🫶

so, reminder from last time: 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 — it waits if the socket literally cannot write at this moment. and honestly? that's kind of a slay for development, because you don't have to worry about what to do in those cases. the code just stops until it can continue. iconic, low maintenance.

but 💀 in a LOT of cases you do not want that behaviour. instead of stopping and waiting, your app might need to go do other tasks while the socket can't read/write — like updating a GUI, or doing operations on some other socket. main character energy means multitasking.

with a nonblocking socket, trying to read or write to a socket that's currently unable to read or write returns immediately with a non-fatal error. and even though OpenSSL is the one doing the reading/writing to the socket, this nonblocking behaviour propagates all the way up to your application, so OpenSSL I/O functions like SSL_read_ex(3) or SSL_write_ex(3) will not block. no cap 🙅‍♀️

since this page builds on the example from ossl-guide-tls-client-block(7), we're assuming you already know it, and we're only explaining how this example differs. iykyk 💜

🎀 Setting the socket to be nonblocking 🎀

first step in writing an app that supports nonblocking: actually set the socket into nonblocking mode. because a socket will by default be blocking. the exact details on how to do this can differ from one platform to another — annoying, i know — 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, btw. you can absolutely just directly call whatever functions your Operating System provides for this purpose on your platform. your call bestie 💅

🦋 Performing work while waiting for the socket 🦋

in a nonblocking application you're gonna need work to perform in the event that we want to read or write to the socket, but we currently can't. and honestly? that's the whole point of using a nonblocking socket — giving the application the opportunity to do something else. ⭐

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 this in the event that the state of the underlying socket has actually changed (e.g. become readable where it wasn't before), but it doesn't have to be that way — it can retry at any time.

⚠️ important, do not skip this one: you have to retry exactly the same operation 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. same operation or nothing, bestie 🫶

in this demo application we're gonna create a helper function that 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. lowkey the laziest function ever but it's fine.

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:

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, no gatekeeping here. 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 waiting for the socket state to change. but we don't use that timeout capability in this example, for the sake of simplicity. we're keeping it cute and minimal ✨

🧚 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). two very different vibes 💀

so here's the rundown:

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

👀 plot 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. it's giving "don't judge a book by its cover" fr fr.

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. so like, half a relationship 🙈

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

  • 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, 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 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. simple as that, she's organized 💅

🌈 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 that are the same as for a blocking client, and they're explained on the ossl-guide-tls-client-block(7) page. we won't repeat that information here — go read the other page bestie, it's literally right there 🫶

👑 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 is 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:

Okay so picking up right at the handshake loop, bestie — this is the part where we keep calling SSL_connect(3) until it gives us a win 💖

           /* 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 we made earlier to figure out what we should do next. And note: we do not expect an EOF to occur at this stage, so that kind of response gets treated the same way as a fatal error. Periodt.

📨 Sending and receiving data 📨

As with the blocking TLS client demo, we use SSL_write_ex(3) to send data to the server. Same deal as SSL_connect(3) above: because we're using a nonblocking socket, this call could fail with a non-fatal error. In that case we should retry exactly the same SSL_write_ex(3) call again. The parameters must be exactly the same — same pointer to the buffer to write, same length. You must not attempt to send different data on a retry. There is an optional mode (SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER) that 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. See SSL_CTX_set_mode(3) for further details. And as in the TLS client blocking tutorial (ossl-guide-tls-client-block(7)), we write the request 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 do not expect to see an EOF response, so we treat that case in the same way as a fatal error. No cap.

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). Cute, right? 🦋

🛑 Shutting down the connection 🛑

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

If our application was initiating the shutdown then we would expect to see SSL_shutdown(3) give a return value of 0, and then we would continue to call it until we received a return value of 1 (meaning we have successfully completed the shutdown). In this particular example we don't expect SSL_shutdown() to return 0 because we have already received EOF from the server indicating that it has shutdown already. So we just keep calling it until SSL_shutdown() returns 1. Since we are using a nonblocking socket 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:

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

🧹 Final clean up 🧹

As with the blocking TLS 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-tls-client-block(7) to read a tutorial on how to write a blocking TLS client. See ossl-guide-quic-client-block(7) to see how to do the same thing for a QUIC client.

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

Okay that's the whole guide, bestie 💖 This iconic page is from OpenSSL 3.5.9, dated 2026-09-2 — source/version and date sign-off, not the footer line itself. Now go slay that nonblocking TLS client ✨💅

📦 where this page comes from