OSSL_CALLBACK(3SSL)

📦
version 4.0.3 · 11 versions
, in ubuntu stonking

💖 OSSL_CALLBACK 💖

okay bestie, welcome to the OpenSSL core type pages — this one is about OSSL_CALLBACK and OSSL_PASSPHRASE_CALLBACK, the two little function-pointer typedefs that let OpenSSL and providers ask you (or the app) for stuff. it's from the 3SSL manual set, and it's giving "short page, huge responsibility". let's go 🫶

✨ NAME ✨

OSSL_CALLBACK, OSSL_PASSPHRASE_CALLBACK — OpenSSL Core type to define callbacks.

that's it. that's the whole name section. iconic of them honestly 👑

🌸 SYNOPSIS 🌸

#include <openssl/core.h>
typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);
typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size,
                                       size_t *pass_len,
                                       const OSSL_PARAM params[],
                                       void *arg);

copy these exactly, bestie, no cap — a single typo in a typedef signature and the compiler will simply choose violence 💀

🦋 DESCRIPTION 🦋

so, here's the vibe: for certain events or activities, provider functionality may need help from the application or from the calling OpenSSL libraries themselves. for example? user input, or direct (possibly optional) user output — that's the kind of thing that gets implemented this way. ✨

callback functions themselves are always provided by or through the calling OpenSSL libraries, together with a generic pointer to data, arg. and here's the important part, the lowkey main-character rule: as far as the function receiving that pointer to the function pointer and arg is concerned, the data that arg points at is opaque — so you just pass the pointer straight back to the callback function when it's called. don't peek, don't poke, just hand it back. 🙈

💅 OSSL_CALLBACK

this is the generic one. when you call this callback function, the caller is expected to build an OSSL_PARAM(3) array of the data it wants or is expected to pass back, and pass that as params — plus the opaque data pointer it received, as arg. that's the whole deal. 🎀

🎀 OSSL_PASSPHRASE_CALLBACK

this one is the specialised sibling, used specifically to prompt the user for a passphrase. when you call it, you need to hand over a buffer to store the passphrase in with pass, plus its size with pass_size. then the length of the prompted passphrase gets given back to you in *pass_len. slay. 🔥

additional parameters can be passed with the OSSL_PARAM(3) array params — and yes, that sentence in the og page just ends with a comma, we're leaving it exactly as-is because facts are facts, periodt. 💜

⭐ RETURN VALUES ⭐

functions of type OSSL_CALLBACK and OSSL_PASSPHRASE_CALLBACK must return 1 on success and 0 on failure. no in-between, no "eh, 2", no vibes-based returns. it's binary, bestie. ✨

🌈 SEE ALSO 🌈

🧚 HISTORY 🧚

the types described here were added in OpenSSL 3.0. so if you're on something older... ngl, they're not there. 😭

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

⚠️ real talk: that Apache 2.0 bit is not decorative, bestie. use it in compliance with the license, fr fr.

and that's the page!! this came from the OpenSSL 4.0.3 docs, dated 2026-09-29, filed under OSSL_CALLBACK(3SSL) — go forth and write callbacks that return 1, you absolute icon 👑💖🌸

📦 where this page comes from