1 files changed, 127 insertions, 19 deletions

diff --git a/src/lib/libcrypto/man/PEM_read.3 b/src/lib/libcrypto/man/PEM_read.3
index 1469ccd558..49cdd0f3c5 100644
--- a/src/lib/libcrypto/man/PEM_read.3
+++ b/src/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 .