LIBRESSL-SSL_CTX_SET_DEFAULT_PASSWD_CB(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

💅 SSL_CTX_SET_DEFAULT_PASS(3) — like, the password-callback page, bestie

okay so we're in the Library Functions Manual and this one is titled SSL_CTX_SET_DEFAULT_PASS(3). Grab a strawberry drink 🍓, because we're talking about how libssl/libcrypto asks you for a password when it's opening an encrypted PEM file. It's giving "let me in" energy. 🔐✨

🌸 SYNOPSIS 🌸

library “libssl” libcrypto #include <openssl/ssl.h>

void
SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb);

void
SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *userdata);

pem_password_cb *
SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx);

void *
SSL_CTX_get_default_passwd_cb_userdata(SSL_CTX *ctx);

✨ DESCRIPTION ✨

So SSL_CTX_set_default_passwd_cb() is the function that sets the password callback — you know, the little function that gets called when the library needs to load a certificate or private key from encrypted PEM format and is like "hiiii what's the password 🥺".

Specifically, the callback gets used by all of these besties:

The function pointer type of the cb argument is documented over in the pem_password_cb(3) manual page — go read that if you want the deets 📖. And here's the thing: if you never call SSL_CTX_set_default_passwd_cb() on ctx, or if you call it with a cb argument of NULL, then PEM_def_callback(3) gets used instead. Default behavior, iconic. 👑

SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to the userdata that will get handed to the password callback when it's invoked. Basically: your little gift basket 🎀 that gets passed along to the callback.

Important vibe check: since the cb you pass to SSL_CTX_set_default_passwd_cb() will only be used for reading and decryption — not for writing and encryption — the library will only ever call it with a verify argument of 0. No cap. 🔥

Now, if your app only needs to read and decrypt one single private key, it can be practical to have the callback handle the password dialog interactively. And this happens by default if neither SSL_CTX_set_default_passwd_cb() nor SSL_CTX_set_default_passwd_cb_userdata() is called — in that case the library uses PEM_def_callback(3) with a userdata argument of NULL. She's got defaults, she's self-sufficient. 💁‍♀️

If you've got several keys to handle, it can be practical to ask for the password once — like with UI_UTIL_read_pw_string(3) — then keep it in memory and use it several times by passing a pointer to it to SSL_CTX_set_default_passwd_cb_userdata(). And good news: PEM_def_callback(3) is able to handle this case too, so calling SSL_CTX_set_default_passwd_cb() is not needed in this case either. You literally don't have to do anything. Slay. 💅

Other items in PEM formatting (certificates) can also be encrypted — but it's however atypical, since certificate information is considered public. Like, why would you lock that, it's already on the timeline. 🤷‍♀️

🦋 RETURN VALUES 🦋

  • SSL_CTX_get_default_passwd_cb() — returns a function pointer to the password callback currently set in ctx, or NULL if none is set.
  • SSL_CTX_get_default_passwd_cb_userdata() — returns a pointer to the userdata currently set in ctx, or NULL if none is set.

Simple. Clean. We love a getter that just tells you the truth. 🫶

🍓 EXAMPLES 🍓

The following example provides a subset of the functionality of PEM_def_callback(3) — except that PEM_def_callback(3) does not NUL-terminate and copies up to size rather than size - 1 bytes. It interprets userdata as a NUL-terminated string and copies it to the password buffer, truncating the copy if it does not fit.

int
trivial_passwd_cb(char *password, int size, int verify, void *userdata)
{
        strlcpy(password, userdata, size);
        return strlen(password);
}

Look at her. Tiny. Efficient. Lowkey doing the most with the least. ⭐

🌈 SEE ALSO 🌈

👑 HISTORY 👑

  • SSL_CTX_set_default_passwd_cb() first appeared in SSLeay 0.6.2 and has been available since OpenBSD 2.4. Ancient. Legendary. Still here. 💀
  • SSL_CTX_set_default_passwd_cb_userdata() first appeared in OpenSSL 0.9.4 and has been available since OpenBSD 2.6.
  • SSL_CTX_get_default_passwd_cb() and SSL_CTX_get_default_passwd_cb_userdata() first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 6.3. The getters are the babies of the family, and honestly? They ate. 🎀

and that's the page!! mwah 💖 This SSL_CTX_SET_DEFAULT_PASSWD_CB(3) page is brought to you by Debian, dated June 8, 2025 — go forth and set your passwd callbacks responsibly, bestie 🧚‍♀️✨

📦 where this page comes from