SSL_SET_ASYNC_CALLBACK(3SSL)

💖 SSL_SET_ASYNC_CALLBACK 💖

okay bestie, this is the <openssl/ssl.h> page about async operations — the SSL_SET_ASYNC_CALLBACK(3SSL) situation, part of the OpenSSL fam. if your crypto provider does things ✨later✨ and needs to ping you when it's done, this is the page, iykyk 🦋

---

✨ NAME ✨

SSL_CTX_set_async_callback, SSL_CTX_set_async_callback_arg, SSL_set_async_callback, SSL_set_async_callback_arg, SSL_get_async_status, SSL_async_callback_fn — literally the whole squad for managing asynchronous operations 👑

---

🌈 SYNOPSIS 🌈

#include <openssl/ssl.h>

typedef int (*SSL_async_callback_fn)(SSL *s, void *arg);
int SSL_CTX_set_async_callback(SSL_CTX *ctx, SSL_async_callback_fn callback);
int SSL_CTX_set_async_callback_arg(SSL_CTX *ctx, void *arg);
int SSL_set_async_callback(SSL *s, SSL_async_callback_fn callback);
int SSL_set_async_callback_arg(SSL *s, void *arg);
int SSL_get_async_status(SSL *s, int *status);

---

💅 DESCRIPTION 💅

so here's the tea, function by function 🍓

• SSL_CTX_set_async_callback() — sets an asynchronous callback function. every single SSL object born from this SSL_CTX inherits that callback, no cap. and if a provider supports the callback mechanism, it gets called automatically when SSL_MODE_ASYNC has been set and the provider finishes a cryptography operation — that's how it tells your app "hey bestie, come resume the paused work flow" 🫶
• SSL_CTX_set_async_callback_arg() — sets the callback argument. that's it, that's the job 💖
• SSL_set_async_callback() — lets an application set a callback on an asynchronous SSL object, so when a provider wraps up a cryptography operation, the callback fires to notify the application to resume the paused work flow ✨
• SSL_set_async_callback_arg() — sets an argument for the SSL object for when that callback above gets called 🎀
• SSL_get_async_status() — returns the provider status. this one is basically the provider-to-application hotline. during an SSL session, cryptographic operations get dispatched to a provider, and the provider status is so useful for an app to know whether the operation was successfully dispatched. if the provider doesn't support this extra callback method, ASYNC_STATUS_UNSUPPORTED comes back at you. for the whole description of every status value, go peek at ASYNC_WAIT_CTX_set_status() 👀

🌸 an example, because visuals help 🌸

so like, the above functions in action would be:

1. the application sets the async callback and callback data on an SSL connection by calling SSL_set_async_callback().
2. the application sets SSL_MODE_ASYNC and makes an asynchronous SSL call.
3. OpenSSL submits the asynchronous request to the provider. if a retry occurs at this point, then the status within the ASYNC_WAIT_CTX would be set and the async callback function would be called (goto Step 7).
4. the OpenSSL provider pauses the current job and returns, so the application can keep processing other connections in the meantime ✨ multitasking queen.
5. at a future point in time (probably via a polling mechanism or via an interrupt), the provider will become aware that the asynchronous request has finished processing.
6. the provider will call the application's callback, passing the callback data as a parameter.
7. the callback function should then run. note: it is a requirement that the callback function is small and nonblocking, because it will be run in the context of a polling mechanism or an interrupt. so like… keep it tiny, bestie 🙈
8. it is the application's responsibility, via the callback function, to schedule recalling the OpenSSL asynchronous function and to continue processing.
9. the callback function has the option to check the status returned via SSL_get_async_status() to determine whether a retry happened instead of the request being submitted — which lets you do different processing if required. flexible 💅

---

🔥 RETURN VALUES 🔥

SSL_CTX_set_async_callback(), SSL_set_async_callback(), SSL_CTX_set_async_callback_arg(), SSL_CTX_set_async_callback_arg() and SSL_get_async_status() return 1 on success or 0 on error. that's the whole vibe check: 1 slay, 0 not slay 😭

---

🦋 SEE ALSO 🦋

• ssl(7)

---

👑 HISTORY 👑

SSL_CTX_set_async_callback(), SSL_CTX_set_async_callback_arg(), SSL_set_async_callback(), SSL_set_async_callback_arg() and SSL_get_async_status() were first added to OpenSSL 3.0. little baby functions, all grown up now 🥹

---

💜 COPYRIGHT 💜

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

---

and that's a wrap, bestie 🎀 this was OpenSSL 4.0.3, dated 2026-09-29 — SSL_SET_ASYNC_CALLBACK(3SSL), signing off 💖✨