.Dd $Mdocdate: October 12 2014 $
.Dt SSL_CTX_SET_DEFAULT_PASSWD_CB 3
.Os
.Sh NAME
.Nm SSL_CTX_set_default_passwd_cb ,
.Nm SSL_CTX_set_default_passwd_cb_userdata
.Nd set passwd callback for encrypted PEM file handling
.Sh SYNOPSIS
.In openssl/ssl.h
.Ft void
.Fn SSL_CTX_set_default_passwd_cb "SSL_CTX *ctx" "pem_password_cb *cb"
.Ft void
.Fn SSL_CTX_set_default_passwd_cb_userdata "SSL_CTX *ctx" "void *u"
.Ft int
.Fn pem_passwd_cb "char *buf" "int size" "int rwflag" "void *userdata"
.Sh DESCRIPTION
.Fn SSL_CTX_set_default_passwd_cb
sets the default password callback called when loading/storing a PEM
certificate with encryption.
.Pp
.Fn SSL_CTX_set_default_passwd_cb_userdata
sets a pointer to userdata
.Fa u
which will be provided to the password callback on invocation.
.Pp
The
.Fn pem_passwd_cb ,
which must be provided by the application,
hands back the password to be used during decryption.
On invocation a pointer to
.Fa userdata
is provided.
The pem_passwd_cb must write the password into the provided buffer
.Fa buf
which is of size
.Fa size .
The actual length of the password must be returned to the calling function.
.Fa rwflag
indicates whether the callback is used for reading/decryption
.Pq Fa rwflag No = 0
or writing/encryption
.Pq Fa rwflag No = 1 .
.Sh NOTES
When loading or storing private keys, a password might be supplied to protect
the private key.
The way this password can be supplied may depend on the application.
If only one private key is handled, it can be practical to have
.Fn pem_passwd_cb
handle the password dialog interactively.
If several keys have to be handled, it can be practical to ask for the password
once, then keep it in memory and use it several times.
In the last case, the password could be stored into the
.Fa userdata
storage and the
.Fn pem_passwd_cb
only returns the password already stored.
.Pp
When asking for the password interactively,
.Fn pem_passwd_cb
can use
.Fa rwflag
to check whether an item shall be encrypted
.Pq Fa rwflag No = 1 .
In this case the password dialog may ask for the same password twice for
comparison in order to catch typos which would make decryption impossible.
.Pp
Other items in PEM formatting (certificates) can also be encrypted; it is
however atypical, as certificate information is considered public.
.Sh RETURN VALUES
.Fn SSL_CTX_set_default_passwd_cb
and
.Fn SSL_CTX_set_default_passwd_cb_userdata
do not provide diagnostic information.
.Sh EXAMPLES
The following example returns the password provided as
.Fa userdata
to the calling function.
The password is considered to be a
.Sq \e0
terminated string.
If the password does not fit into the buffer, the password is truncated.
.Bd -literal
int pem_passwd_cb(char *buf, int size, int rwflag, void *password)
{
	strncpy(buf, (char *)password, size);
	buf[size - 1] = '\e0';
	return strlen(buf);
}
.Ed
.Sh SEE ALSO
.Xr ssl 3 ,
.Xr SSL_CTX_use_certificate 3