SSL_CTX_SET_DEFAULT_PASSWD_CB(3) | Library Functions Manual | SSL_CTX_SET_DEFAULT_PASSWD_CB(3)

# 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` — set or get passwd callback for encrypted PEM file handling

# 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

`SSL_CTX_set_default_passwd_cb`() sets the password callback for loading a certificate or private key from encrypted PEM format. In particular, the callback is used by SSL_CTX_use_certificate_file(3), SSL_use_certificate_file(3), SSL_CTX_use_certificate_chain_file(3), SSL_use_certificate_chain_file(3), SSL_CTX_use_certificate_chain_mem(3), SSL_CTX_use_PrivateKey_file(3), SSL_use_PrivateKey_file(3), SSL_CTX_use_RSAPrivateKey_file(3), and SSL_use_RSAPrivateKey_file(3).

The function pointer type of the cb argument is documented in the pem_password_cb(3) manual page. If `SSL_CTX_set_default_passwd_cb`() is not called on ctx or if it is called with a cb argument of `NULL`, PEM_def_callback(3) is used instead.

`SSL_CTX_set_default_passwd_cb_userdata`() sets a pointer to the userdata which will be provided to the password callback on invocation.

Since the cb passed to `SSL_CTX_set_default_passwd_cb`() will only be used for reading and decryption and not for writing and encryption, the library will only call it with a verify argument of 0.

If an application program only needs to read and decrypt one single private key, it can be practical to have the callback handle the password dialog interactively. 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`.

If several keys have to be handled, it can be practical to ask for the password once, for example using 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`(). 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.

Other items in PEM formatting (certificates) can also be encrypted; it is however atypical, as certificate information is considered public.

# 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.

# 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);
    }

# SEE ALSO

pem_password_cb(3), ssl(3), SSL_CTX_use_certificate(3)

# HISTORY

`SSL_CTX_set_default_passwd_cb`() first appeared in SSLeay 0.6.2 and has been available since OpenBSD 2.4.

`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.

June 8, 2025 | Debian