-.\" $OpenBSD: SSL_CTX_set_default_passwd_cb.3,v 1.7 2018/04/02 02:06:14 schwarze Exp $
+.\" $OpenBSD: SSL_CTX_set_default_passwd_cb.3,v 1.8 2023/09/19 08:18:13 schwarze Exp $
.\" full merge up to: OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400
-.\" selective merge up to: OpenSSL 2947af32 Nov 19 00:10:05 2016 +0100
+.\" selective merge up to: OpenSSL 18bad535 Apr 9 15:13:55 2019 +0100
.\"
-.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Lutz Jaenicke <jaenicke@openssl.org>
.\" and Christian Heimes <cheimes@redhat.com>.
.\" Copyright (c) 2000, 2001, 2016 The OpenSSL Project. All rights reserved.
.\"
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd $Mdocdate: April 2 2018 $
+.Dd $Mdocdate: September 19 2023 $
.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 ,
.Nm SSL_CTX_get_default_passwd_cb ,
-.Nm SSL_CTX_get_default_passwd_cb_userdata ,
-.Nm pem_password_cb
+.Nm SSL_CTX_get_default_passwd_cb_userdata
.Nd set or get 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"
+.Fn SSL_CTX_set_default_passwd_cb_userdata "SSL_CTX *ctx" "void *userdata"
.Ft pem_password_cb *
.Fn SSL_CTX_get_default_passwd_cb "SSL_CTX *ctx"
.Ft void *
.Fn SSL_CTX_get_default_passwd_cb_userdata "SSL_CTX *ctx"
-.In openssl/pem.h
-.Ft typedef int
-.Fn pem_password_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.
+sets the password callback for loading a certificate or private key
+from encrypted PEM format.
+In particular, the callback is used by
+.Xr SSL_CTX_use_certificate_file 3 ,
+.Xr SSL_use_certificate_file 3 ,
+.Xr SSL_CTX_use_certificate_chain_file 3 ,
+.Xr SSL_use_certificate_chain_file 3 ,
+.Xr SSL_CTX_use_certificate_chain_mem 3 ,
+.Xr SSL_CTX_use_PrivateKey_file 3 ,
+.Xr SSL_use_PrivateKey_file 3 ,
+.Xr SSL_CTX_use_RSAPrivateKey_file 3 ,
+and
+.Xr SSL_use_RSAPrivateKey_file 3 .
+.Pp
+The function pointer type of the
+.Fa cb
+argument is documented in the
+.Xr pem_password_cb 3
+manual page.
+If
+.Fn SSL_CTX_set_default_passwd_cb
+is not called on
+.Fa ctx
+or if it is called with a
+.Fa cb
+argument of
+.Dv NULL ,
+.Xr PEM_def_callback 3
+is used instead.
.Pp
.Fn SSL_CTX_set_default_passwd_cb_userdata
-sets a pointer to userdata
-.Fa u
+sets a pointer to the
+.Fa userdata
which will be provided to the password callback on invocation.
.Pp
-The
-password callback
-.Fa 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 password callback 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 .
+Since the
+.Fa cb
+passed to
+.Fn 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
+.Fa verify
+argument of 0.
.Pp
-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 the
+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.
-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
+This happens by default if neither
+.Fn SSL_CTX_set_default_passwd_cb
+nor
+.Fn SSL_CTX_set_default_passwd_cb_userdata
+is called.
+In that case, the library uses
+.Xr PEM_def_callback 3
+with a
.Fa userdata
-storage and the callback only returns the password already stored.
+argument of
+.Dv NULL .
.Pp
-When asking for the password interactively, the callback 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.
+If several keys have to be handled, it can be practical
+to ask for the password once, for example using
+.Xr UI_UTIL_read_pw_string 3 ,
+then keep it in memory and use it several times by passing a pointer to it to
+.Fn SSL_CTX_set_default_passwd_cb_userdata .
+.Xr PEM_def_callback 3
+is able to handle this case, too, so calling
+.Fn SSL_CTX_set_default_passwd_cb
+is not needed in this case either.
.Pp
Other items in PEM formatting (certificates) can also be encrypted; it is
however atypical, as certificate information is considered public.
.Dv NULL
if none is set.
.Sh EXAMPLES
-The following example returns the password provided as
+The following example provides a subset of the functionality of
+.Xr PEM_def_callback 3 .
+It interprets
.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.
+as a NUL-terminated string and copies it to the
+.Fa password
+buffer, truncating the copy if it does not fit.
.Bd -literal
-int pem_passwd_cb(char *buf, int size, int rwflag, void *password)
+int
+trivial_passwd_cb(char *password, int size, int verify, void *userdata)
{
- strncpy(buf, (char *)password, size);
- buf[size - 1] = '\e0';
- return strlen(buf);
+ strlcpy(password, userdata, size);
+ return strlen(password);
}
.Ed
.Sh SEE ALSO
+.Xr pem_password_cb 3 ,
.Xr ssl 3 ,
.Xr SSL_CTX_use_certificate 3
.Sh HISTORY
projects / openbsd / commitdiff