Remove the duplicate documentation of pem_password_cb(3).

While here, also:

* Avoid the misleading term "default password callback" because none of
the functions in SSL_CTX_use_certificate(3) support overriding it.
* Do not talk about "storing", "writing", and "encryption" since the cb
passed to SSL_CTX_set_default_passwd_cb(3) is never used for any of that.
* List the functions using cb.
* Document what happens by default.
* Remove the misleading words "which must be provided by the application"
because all this is actually optional.
* Make several wordings more precise.
* Below EXAMPLES, fix argument naming to agree with pem_password_cb(3),
clarify the description of what the example does, and, as suggested by tb@,
use strlcpy(3).

OK tb@

1 files changed, 94 insertions, 56 deletions

diff --git a/src/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3 b/src/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3
index 7ab9633f5c..4e119132b2 100644
--- a/src/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3
+++ b/src/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3
@@ -1,8 +1,25 @@
-.\" $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.
 .\"
@@ -50,75 +67,95 @@
 .\" 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.
@@ -137,22 +174,23 @@ or
 .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