SSL_CTX_SET_DEFAULT_PASSWD_CB(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 SSL_CTX_SET_DEFAULT_PASSWD_CB 💖

okay bestie, so this is an OpenSSL page — section 3SSL, the SSL_CTX_set_default_passwd_cb family, and we're about to have a whole moment about password callbacks. grab a strawberry milk, we're doing this 🍓

✨ NAME ✨

SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata, SSL_CTX_get_default_passwd_cb, SSL_CTX_get_default_passwd_cb_userdata, SSL_set_default_passwd_cb, SSL_set_default_passwd_cb_userdata, SSL_get_default_passwd_cb, SSL_get_default_passwd_cb_userdata — the whole girlgang that sets or gets the passwd callback for encrypted PEM file handling. literally their whole job 💅

🎀 SYNOPSIS 🎀

#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 *u);
pem_password_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx);
void *SSL_CTX_get_default_passwd_cb_userdata(SSL_CTX *ctx);

void SSL_set_default_passwd_cb(SSL *s, pem_password_cb *cb);
void SSL_set_default_passwd_cb_userdata(SSL *s, void *u);
pem_password_cb *SSL_get_default_passwd_cb(SSL *s);
void *SSL_get_default_passwd_cb_userdata(SSL *s);

🦋 DESCRIPTION 🦋

so. here's the tea ☕

  • SSL_CTX_set_default_passwd_cb() — sets the default password callback that gets called when you're loading or storing a PEM certificate with encryption. it's giving "the one who handles the secrets."
  • SSL_CTX_set_default_passwd_cb_userdata() — sets a pointer to userdata, u, and that pointer is what gets handed to the password callback every time it's invoked. an icon delivering snacks to the callback fr fr 🫶
  • SSL_CTX_get_default_passwd_cb() — returns a function pointer to the password callback currently set in ctx. and if nobody ever explicitly set a callback? you get the NULL pointer back. no callback, no vibes 😭
  • SSL_CTX_get_default_passwd_cb_userdata() — returns a pointer to the userdata currently set in ctx. same deal: if no userdata was explicitly set, the NULL pointer comes home to you.

then the SSL-object girlies:

  • SSL_set_default_passwd_cb(), SSL_set_default_passwd_cb_userdata(), SSL_get_default_passwd_cb() and SSL_get_default_passwd_cb_userdata() do exactly the same thing as their SSL_CTX counterparts — except they're operating on an SSL object instead of an SSL_CTX. same energy, different host 💫

and now the callback itself, which is the main character here 👑

the password callback must be provided by the application — OpenSSL is not gonna write it for you, bestie — and it hands back the password to be used during decryption. on invocation it gets a pointer to userdata. the function has to store the password into the provided buffer buf, which is of size size. the actual length of the password must be returned to the calling function. and rwflag tells you whether the callback is being used for reading/decryption (rwflag=0) or writing/encryption (rwflag=1). for more details, go read pem_password_cb(3), no cap.

🌸 NOTES 🌸

when you're loading or storing private keys, a password might be supplied to protect the private key. how that password gets supplied is kind of an application-by-application thing, and honestly? valid.

  • if only one private key is being handled, it can be practical to have the callback handle the password dialog interactively. cute, personal, one-on-one.
  • if several keys have to be handled, it can be practical to ask for the password once, keep it in memory, and reuse it several times. efficiency queen ✨
  • and in that last case, the password could be stored into the userdata storage, with the callback only returning the password that's already stored there. reusing her own notes, obsessed.

when asking for the password interactively, the callback can use rwflag to check whether an item shall be encrypted (rwflag=1). and in that case, the password dialog may ask for the same password twice for comparison — to catch typos, which would make decryption literally impossible. protect yourself 💀

other items in PEM formatting (certificates) can also be encrypted — however, it's not usual, since certificate information is considered public. so like, you can, but why would you 🙈

⭐ RETURN VALUES ⭐

these functions do not provide diagnostic information. that's it. that's the whole section. they're not here to explain themselves 💅

🌈 EXAMPLES 🌈

here's an example that returns the password provided as userdata to the calling function. the password is considered to be a '\0' terminated string. and if the password does not fit into the buffer? the password is truncated. so watch that buffer size, bestie.

int my_cb(char *buf, int size, int rwflag, void *u)
{
    strncpy(buf, (char *)u, size);
    buf[size - 1] = '\0';
    return strlen(buf);
}

👀 SEE ALSO 👀

🧚 HISTORY 🧚

SSL_CTX_get_default_passwd_cb(), SSL_CTX_get_default_passwd_cb_userdata(), SSL_set_default_passwd_cb() and SSL_set_default_passwd_cb_userdata() were added in OpenSSL 1.1.0. glow-up era 🌟

Copyright 2000-2019 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 the whole page, babe! this was OpenSSL 4.0.3, dated 2026-09-2, and you read it all the way through — periodt 💅✨🦋
📦 where this page comes from