SSL_HANDLE_EVENTS(3SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

💖 SSL_HANDLE_EVENTS(3SSL) 💖

okay bestie, gather round, because we're learning about SSL_handle_events — it lives in the 3SSL section of the OpenSSL manual, and honestly? it's giving main character energy for nonblocking apps. let's go 🦋

✨ NAME ✨

SSL_handle_events — advance the async state machine and do network I/O. yes literally, it's the multitasker. 💅

✨ SYNOPSIS ✨

#include <openssl/ssl.h>

int SSL_handle_events(SSL *ssl);

✨ DESCRIPTION ✨

so SSL_handle_events() does all the internal processing that's due on an SSL object right now. and the exact stuff it does? honestly depends on what protocol your SSL object is vibing with. like, it might handle timeout events that have become due, or it might — to the extent that's currently possible — try to do network I/O on one of the BIOs underlying the SSL object. 🫶

the main character use case here is this: if your app uses OpenSSL in nonblocking mode, SSL_handle_events() gives OpenSSL a chance to handle timer events, or to respond when there's new data to read from an underlying BIO, or to jump on the opportunity to write pending data to an underlying BIO. it's the "hey bestie, anything you need rn?" function.

now, SSL_handle_events() can only be used with these types of SSL object:

🌸 DTLS SSL objects

using SSL_handle_events() on an SSL object that's being used with a DTLS method means timeout events get handled properly, the way they should. this is equivalent to a call to DTLSv1_handle_timeout(3). and because SSL_handle_events() handles a superset of the use cases of DTLSv1_handle_timeout(3), it's the one you should prefer for new applications that don't need support for OpenSSL 3.1 or older. glow up, periodt. ✨

when you're using DTLS, your application must call SSL_handle_events() as indicated by calls to SSL_get_event_timeout(3). like, event handling is not performed automatically by calls to other SSL functions such as SSL_read(3) or SSL_write(3). and heads up — this is different to QUIC, which also performs event handling implicitly. see below, iykyk. 👇

🌈 QUIC connection SSL objects

using SSL_handle_events() on an SSL object that represents a QUIC connection means timeout events get handled properly, incoming network data gets processed, and queued outgoing network data gets written — but only if the underlying BIO has the capacity to accept it. 💅

so normally, when an app uses an SSL object in blocking mode, it doesn't need to call SSL_handle_events() at all, because OpenSSL does ticking internally on an automatic basis. (yes, auto-ticking, iconic.) but if your app uses a QUIC connection in nonblocking mode, it must — at a minimum — make sure SSL_handle_events() gets called periodically so timeout events actually get handled. and how do you know when you next need to call it for that purpose (if at all)? call SSL_get_event_timeout(3). it'll tell you. 🎀

calling SSL_handle_events() on a QUIC connection SSL object that's being used in blocking mode is not necessary — unless no I/O calls (like SSL_read(3) or SSL_write(3)) will be made to the object for a substantial period of time. so long as at least one call to the SSL object is blocking, no such call is needed. that said, SSL_handle_events() may optionally be used on a QUIC connection object if you want to. no pressure, your choice. 💁♀️

and with the thread-assisted mode of operation OSSL_QUIC_client_thread_method(3), it is unnecessary to call SSL_handle_events(), because the assist thread handles the QUIC connection events for you. teamwork, slay. 🧚

💀 the no-op zone

calling SSL_handle_events() on any other kind of SSL object is a no-op. and that's considered a success case. so if nothing happens, you didn't do it wrong, bestie. 🙈

important note: SSL_handle_events() supersedes the older DTLSv1_handle_timeout(3) function for all use cases. all of them. every single one. 👑

✨ RETURN VALUES ✨

returns 1 on success and 0 on failure. that's it, that's the whole vibe. ⭐

✨ SEE ALSO ✨

✨ HISTORY ✨

the SSL_handle_events() function was added in OpenSSL 3.2. a relatively fresh icon. 👑

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 page, bestie!! 💜 this was version 4.0.3, dated 2026-09-29, and it's the SSL_HANDLE_EVENTS(3SSL) manual page. go forth and handle your events, you absolute legend. 🎀✨🦋

📦 where this page comes from