Document PEM_def_callback(3).

Move pem_password_cb(3) to the file PEM_read(3) and rewrite
its description from scratch for precision and conciseness.
Plus some minor improvements in the vicinity.
Tweaks and OK tb@.

3 files changed, 158 insertions, 106 deletions

diff --git a/lib/libcrypto/man/PEM_bytes_read_bio.3 b/lib/libcrypto/man/PEM_bytes_read_bio.3
index d3a664ba748..d1148edfe0e 100644
--- a/lib/libcrypto/man/PEM_bytes_read_bio.3
+++ b/lib/libcrypto/man/PEM_bytes_read_bio.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PEM_bytes_read_bio.3,v 1.4 2020/06/12 18:16:13 schwarze Exp $
+.\" $OpenBSD: PEM_bytes_read_bio.3,v 1.5 2020/06/15 14:13:14 schwarze Exp $
 .\" selective merge up to:
 .\" OpenSSL PEM_bytes_read_bio.pod 7671342e Feb 29 15:47:12 2016 -0600
 .\"
@@ -65,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 12 2020 $
+.Dd $Mdocdate: June 15 2020 $
 .Dt PEM_BYTES_READ_BIO 3
 .Os
 .Sh NAME
@@ -79,31 +79,31 @@
 .Fa "long *plen"
 .Fa "char **pnm"
 .Fa "const char *name"
-.Fa "BIO *bp"
+.Fa "BIO *in_bp"
 .Fa "pem_password_cb *cb"
 .Fa "void *u"
 .Fc
 .Sh DESCRIPTION
 .Fn PEM_bytes_read_bio
-reads PEM-formatted (RFC 1421) data from the BIO
-.Fa bp
-for the data type given in
+reads and PEM decodes the first object of type
 .Fa name
-(RSA PRIVATE KEY, CERTIFICATE, etc.).
+.Pq e.g. RSA PRIVATE KEY, CERTIFICATE, etc.\&
+from
+.Fa in_bp .
 If multiple PEM-encoded data structures are present in the same stream,
-.Fn PEM_bytes_read_bio
-will skip non-matching data types and continue reading.
-Non-PEM data present in the stream may cause an error.
+it skips non-matching data types and continues reading.
+Before reading each PEM object, lines not starting with
+.Qq "-----BEGIN "
+are also skipped; see
+.Xr PEM_read_bio 3
+for details of PEM parsing.
 .Pp
 The PEM header may indicate that the following data is encrypted; if so,
-the data will be decrypted, waiting on user input to supply a passphrase
-if needed.
-The password callback
+the data is decrypted, optionally using
 .Fa cb
-and rock
-.Fa u
-are used to obtain the decryption passphrase, if applicable.
-For more details, see
+and
+.Fa u ,
+as described in
 .Xr pem_password_cb 3 .
 .Pp
 Some data types have compatibility aliases, such as a file containing
@@ -175,6 +175,8 @@ Additional types of errors can result from
 .Xr PEM_ASN1_read 3 ,
 .Xr PEM_read 3 ,
 .Xr PEM_read_bio_PrivateKey 3
+.Sh STANDARDS
+RFC 1421: Privacy Enhancement for Internet Electronic Mail (PEM), Part I
 .Sh HISTORY
 .Fn PEM_bytes_read_bio
 first appeared in OpenSSL 0.9.7 and has been available since
diff --git a/lib/libcrypto/man/PEM_read.3 b/lib/libcrypto/man/PEM_read.3
index 1469ccd558b..49cdd0f3c5b 100644
--- a/lib/libcrypto/man/PEM_read.3
+++ b/lib/libcrypto/man/PEM_read.3
@@ -1,7 +1,24 @@
-.\"	$OpenBSD: PEM_read.3,v 1.10 2020/06/12 11:37:42 schwarze Exp $
-.\"	OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
+.\" $OpenBSD: PEM_read.3,v 1.11 2020/06/15 14:13:14 schwarze Exp $
+.\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100
 .\"
-.\" This file was written by Viktor Dukhovni
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2020 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 Viktor Dukhovni
 .\" and by Rich Salz <rsalz@openssl.org>.
 .\" Copyright (c) 2016 The OpenSSL Project.  All rights reserved.
 .\"
@@ -49,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 12 2020 $
+.Dd $Mdocdate: June 15 2020 $
 .Dt PEM_READ 3
 .Os
 .Sh NAME
@@ -57,8 +74,10 @@
 .Nm PEM_write_bio ,
 .Nm PEM_read ,
 .Nm PEM_read_bio ,
+.Nm PEM_get_EVP_CIPHER_INFO ,
 .Nm PEM_do_header ,
-.Nm PEM_get_EVP_CIPHER_INFO
+.Nm PEM_def_callback ,
+.Nm pem_password_cb
 .Nd PEM encoding routines
 .Sh SYNOPSIS
 .In openssl/pem.h
@@ -107,6 +126,20 @@
 .Fa "pem_password_cb *cb"
 .Fa "void *u"
 .Fc
+.Ft int
+.Fo PEM_def_callback
+.Fa "char *password"
+.Fa "int size"
+.Fa "int verify"
+.Fa "void *u"
+.Fc
+.Ft typedef int
+.Fo pem_password_cb
+.Fa "char *password"
+.Fa "int size"
+.Fa "int verify"
+.Fa "void *u"
+.Fc
 .Sh DESCRIPTION
 These functions read and write PEM-encoded objects, using the PEM type
 .Fa name ,
@@ -224,34 +257,83 @@ unknown or some internal error happens, 0 is returned.
 can then be used to decrypt the data if the header indicates encryption.
 The
 .Fa cinfo
-argument is a pointer to the structure initialized by the previous call
+argument is a pointer to the structure initialized by a preceding call
 to
 .Fn PEM_get_EVP_CIPHER_INFO .
+If that structure indicates the absence of encryption,
+.Fn PEM_do_header
+returns sucessfully without taking any action.
 The
 .Fa data
 and
 .Fa len
-arguments are those returned by the previous call to
+arguments are used both to pass in the encrypted data that was
+returned in the same arguments from the preceding call to
 .Fn PEM_read
 or
-.Fn PEM_read_bio .
+.Fn PEM_read_bio
+and to pass out the decrypted data.
+.Pp
+The callback function
+.Fa cb
+is used to obtain the encryption
+.Fa password ;
+if
+.Fa cb
+is
+.Dv NULL ,
+.Fn PEM_def_callback
+is used instead.
 The
+.Fa password
+buffer needs to be at least
+.Fa size
+bytes long.
+.Fn PEM_def_callback
+silently truncates the NUL-terminated byte string
+.Fa u
+to at most
+.Fa num
+bytes and copies it into
+.Fa password
+without a terminating NUL byte.
+If
+.Fa u
+is
+.Dv NULL ,
+.Fn PEM_def_callback
+instead prompts the user for the password with echoing turned off
+by calling
+.Xr EVP_read_pw_string_min 3
+internally.
+In this case, the
+.Fa size
+is silently reduced to at most
+.Dv BUFSIZ
+and at most
+.Fa size No \- 1
+bytes are accepted from the user and copied into the byte string buffer
+.Fa password .
+A callback function
 .Fa cb
-and
+supplied by the application may use
 .Fa u
-arguments make it possible to override the default password prompt
-function as described in
-.Xr PEM_read_PrivateKey 3 .
-On successful completion, the
-.Fa data
-is decrypted in place, and
-.Fa len
-is updated to indicate the plaintext length.
+for a different purpose than
+.Fn PEM_def_callback
+does, e.g., as auxiliary data to use while acquiring the password.
+For example, a GUI application might pass a window handle.
+If the
+.Fa verify
+flag is non-zero, the user is prompted twice for the password to
+make typos less likely and it is checked that both inputs agree.
+This flag is not set by
+.Fn PEM_do_header
+nor by other read functions.
 .Pp
 If the data is a priori known to not be encrypted, then neither
-.Fn PEM_do_header
-nor
 .Fn PEM_get_EVP_CIPHER_INFO
+nor
+.Fn PEM_do_header
 need to be called.
 .Sh RETURN VALUES
 .Fn PEM_read
@@ -276,6 +358,28 @@ return 1 on success or 0 on failure.
 The
 .Fa data
 is likely meaningless if these functions fail.
+.Pp
+.Fn PEM_def_callback
+returns the number of bytes stored into
+.Fa buf
+or a negative value on failure, and
+.Fa cb
+is expected to behave in the same way.
+If
+.Fa u
+is
+.Dv NULL ,
+.Fn PEM_def_callback
+fails if
+.Fa num
+is less than 5
+or if an error occurs trying to prompt the user for the password.
+Otherwise, it fails when
+.Fa num
+is negative.
+The details of the circumstances that cause
+.Fa cb
+to fail may differ.
 .Sh SEE ALSO
 .Xr crypto 3 ,
 .Xr d2i_PKCS8PrivateKey_bio 3 ,
@@ -299,3 +403,7 @@ and
 first appeared in SSLeay 0.6.0.
 These functions have been available since
 .Ox 2.4 .
+.Pp
+.Fn PEM_def_callback
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.2 .
diff --git a/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 b/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
index 3799baa0400..cc58640b1c9 100644
--- a/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
+++ b/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PEM_read_bio_PrivateKey.3,v 1.17 2020/06/12 11:37:42 schwarze Exp $
+.\" $OpenBSD: PEM_read_bio_PrivateKey.3,v 1.18 2020/06/15 14:13:14 schwarze Exp $
 .\" full merge up to:
 .\" OpenSSL man3/PEM_read_bio_PrivateKey.pod 18bad535 Apr 9 15:13:55 2019 +0100
 .\" OpenSSL man3/PEM_read_CMS.pod 83cf7abf May 29 13:07:08 2018 +0100
@@ -51,11 +51,10 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 12 2020 $
+.Dd $Mdocdate: June 15 2020 $
 .Dt PEM_READ_BIO_PRIVATEKEY 3
 .Os
 .Sh NAME
-.Nm pem_password_cb ,
 .Nm PEM_read_bio_PrivateKey ,
 .Nm PEM_read_PrivateKey ,
 .Nm PEM_write_bio_PrivateKey ,
@@ -149,13 +148,6 @@
 .Nd PEM routines
 .Sh SYNOPSIS
 .In openssl/pem.h
-.Ft typedef int
-.Fo pem_password_cb
-.Fa "char *buf"
-.Fa "int size"
-.Fa "int rwflag"
-.Fa "void *u"
-.Fc
 .Ft EVP_PKEY *
 .Fo PEM_read_bio_PrivateKey
 .Fa "BIO *bp"
@@ -754,7 +746,9 @@
 .Sh DESCRIPTION
 The PEM functions read or write structures in PEM format.
 In this sense PEM format is simply base64-encoded data surrounded by
-header lines.
+header lines; see
+.Xr PEM_read 3
+for more details.
 .Pp
 For more details about the meaning of arguments see the
 .Sx PEM function arguments
@@ -1050,10 +1044,14 @@ If this parameter is set to
 .Dv NULL ,
 then the private key is written in unencrypted form.
 .Pp
-The
+The optional arguments
+.Fa u
+and
 .Fa cb
-argument is the callback to use when querying for the passphrase used
-for encrypted PEM structures (normally only private keys).
+are a passphrase used for encrypting a PEM structure
+or a callback to obtain the passphrase; see
+.Xr pem_password_cb 3
+for details.
 .Pp
 For the PEM write routines, if the
 .Fa kstr
@@ -1066,62 +1064,6 @@ bytes at
 are used as the passphrase and
 .Fa cb
 is ignored.
-.Pp
-If the
-.Fa cb
-parameter is set to
-.Dv NULL
-and the
-.Fa u
-parameter is not
-.Dv NULL ,
-then the
-.Fa u
-parameter is interpreted as a null terminated string to use as the
-passphrase.
-If both
-.Fa cb
-and
-.Fa u
-are
-.Dv NULL ,
-then the default callback routine is used, which will typically
-prompt for the passphrase on the current terminal with echoing
-turned off.
-.Pp
-The default passphrase callback is sometimes inappropriate (for example
-in a GUI application) so an alternative can be supplied.
-The callback routine has the following form:
-.Bd -filled -offset inset
-.Ft int
-.Fo cb
-.Fa "char *buf"
-.Fa "int size"
-.Fa "int rwflag"
-.Fa "void *u"
-.Fc
-.Ed
-.Pp
-.Fa buf
-is the buffer to write the passphrase to.
-.Fa size
-is the maximum length of the passphrase, i.e. the size of
-.Fa buf .
-.Fa rwflag
-is a flag which is set to 0 when reading and 1 when writing.
-A typical routine will ask the user to verify the passphrase (for
-example by prompting for it twice) if
-.Fa rwflag
-is 1.
-The
-.Fa u
-parameter has the same value as the
-.Fa u
-parameter passed to the PEM routine.
-It allows arbitrary data to be passed to the callback by the application
-(for example a window handle in a GUI application).
-The callback must return the number of characters in the passphrase
-or -1 if an error occurred.
 .Ss PEM encryption format
 This old
 .Sy PrivateKey