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