document PEM_ASN1_read(3) and PEM_ASN1_read_bio(3);

tweaks and OK tb@

5 files changed, 236 insertions, 7 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 05b1a54c86..c613fdc293 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.167 2020/06/10 11:43:07 schwarze Exp $
+# $OpenBSD: Makefile,v 1.168 2020/06/12 11:37:42 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -203,6 +203,7 @@ MAN=	\
         OPENSSL_malloc.3 \
         OPENSSL_sk_new.3 \
         OpenSSL_add_all_algorithms.3 \
+        PEM_ASN1_read.3 \
         PEM_bytes_read_bio.3 \
         PEM_read.3 \
         PEM_read_bio_PrivateKey.3 \
diff --git a/src/lib/libcrypto/man/PEM_ASN1_read.3 b/src/lib/libcrypto/man/PEM_ASN1_read.3
new file mode 100644
index 0000000000..cea0c2df68
--- /dev/null
+++ b/src/lib/libcrypto/man/PEM_ASN1_read.3
@@ -0,0 +1,171 @@
+.\" $OpenBSD: PEM_ASN1_read.3,v 1.1 2020/06/12 11:37:42 schwarze Exp $
+.\"
+.\" 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.
+.\"
+.Dd $Mdocdate: June 12 2020 $
+.Dt PEM_ASN1_READ 3
+.Os
+.Sh NAME
+.Nm d2i_of_void ,
+.Nm PEM_ASN1_read ,
+.Nm PEM_ASN1_read_bio
+.Nd PEM and DER decode an arbitrary ASN.1 value
+.Sh SYNOPSIS
+.In openssl/pem.h
+.Ft typedef void *
+.Fo d2i_of_void
+.Fa "void **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft void *
+.Fo PEM_ASN1_read
+.Fa "d2i_of_void *d2i"
+.Fa "const char *name"
+.Fa "FILE *in_fp"
+.Fa "void **val_out"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft void *
+.Fo PEM_ASN1_read_bio
+.Fa "d2i_of_void *d2i"
+.Fa "const char *name"
+.Fa "BIO *in_bp"
+.Fa "void **val_out"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Sh DESCRIPTION
+These functions read one object from
+.Fa in_fp
+or
+.Fa in_bp
+and perform both PEM and DER decoding.
+They are needed when more specific decoding functions
+like those documented in
+.Xr PEM_read_bio_PrivateKey 3
+and
+.Xr PEM_read_SSL_SESSION 3
+are inadequate for the type
+.Fa name .
+.Pp
+For PEM decoding,
+.Xr PEM_bytes_read_bio 3
+is called internally.
+Consequently, the first object of type
+.Fa name
+is returned and preceding objects of other types are discarded.
+If necessary, data is decrypted, using
+.Fa cb
+and/or
+.Fa u
+if they are not
+.Dv NULL ,
+as described in the
+.Xr pem_password_cb 3
+manual page.
+.Pp
+For subsequent DER decoding, pass a
+.Fa d2i
+callback function that is adequate for the type
+.Fa name ,
+typically returning a pointer of a type more specific than
+.Ft void * .
+For example,
+.Xr d2i_ASN1_TYPE 3
+can always be used and its manual page describes the required
+behaviour of the callback function to be passed.
+Normally, passing a more specific function is more useful;
+candidate functions can be found with
+.Ql man -k Nm~^d2i_ .
+.Pp
+For the
+.Fa name
+argument, the
+.Dv PEM_STRING_*
+string constants defined in
+.In openssl/pem.h
+can be used.
+.Pp
+The
+.Fa val_out
+argument is useless and its many dangers are described in detail in the
+.Xr d2i_ASN1_TYPE 3
+manual page.
+To reduce the risk of bugs, always passing
+.Dv NULL
+is recommended.
+.Sh RETURN VALUES
+These functions return a pointer to the decoded object or
+.Dv NULL
+if an error occurs.
+They fail if
+.Xr PEM_bytes_read_bio 3
+fails, for example because of invalid syntax in the input, an unknown
+encryption, or an invalid passphrase entered by the user.
+They also fail if
+.Fa d2i
+returns
+.Dv NULL ,
+for example due to DER decoding errors.
+.Pp
+.Fn PEM_ASN1_read
+may also fail if memory is exhausted.
+.Sh EXAMPLES
+Typical usage of
+.Fn PEM_ASN1_read
+is demonstrated by the implementation of the more specific function
+to PEM and DER decode an X.509 certificate:
+.Bd -literal -offset 2n
+X509 *
+PEM_read_X509(FILE *fp, X509 **val_out, pem_password_cb *cb, void *u)
+{
+        return PEM_ASN1_read((d2i_of_void *)d2i_X509, PEM_STRING_X509,
+            fp, (void **)val_out, cb, u);
+}
+.Ed
+.Sh ERRORS
+Diagnostics that can be retrieved with
+.Xr ERR_get_error 3 ,
+.Xr ERR_GET_REASON 3 ,
+and
+.Xr ERR_reason_error_string 3
+include:
+.Bl -tag -width Ds
+.It Dv ERR_R_BUF_LIB Qq "BUF lib"
+.Fn PEM_ASN1_read
+failed to set up a temporary BIO,
+for example because memory was exhausted.
+.It Dv ERR_R_ASN1_LIB Qq "ASN1 lib"
+.Fa d2i
+returned
+.Dv NULL ,
+for example due to a DER syntax error.
+.El
+.Pp
+Additional types of errors can result from
+.Xr PEM_bytes_read_bio 3 .
+.Sh SEE ALSO
+.Xr BIO_new 3 ,
+.Xr d2i_ASN1_TYPE 3 ,
+.Xr PEM_bytes_read_bio 3 ,
+.Xr PEM_read 3 ,
+.Xr PEM_read_bio_PrivateKey 3 ,
+.Xr PEM_read_SSL_SESSION 3
+.Sh HISTORY
+These functions first appeared in SSLeay 0.5.1
+and have been available since
+.Ox 2.4 .
diff --git a/src/lib/libcrypto/man/PEM_bytes_read_bio.3 b/src/lib/libcrypto/man/PEM_bytes_read_bio.3
index b3cb143cf6..63b8a58d90 100644
--- a/src/lib/libcrypto/man/PEM_bytes_read_bio.3
+++ b/src/lib/libcrypto/man/PEM_bytes_read_bio.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: PEM_bytes_read_bio.3,v 1.2 2018/03/22 21:08:22 schwarze Exp $
+.\"     $OpenBSD: PEM_bytes_read_bio.3,v 1.3 2020/06/12 11:37:42 schwarze Exp $
 .\"     OpenSSL PEM_bytes_read_bio.pod 7671342e Feb 29 15:47:12 2016 -0600
 .\"
 .\" This file was written by Benjamin Kaduk <bkaduk at akamai dot com>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 22 2018 $
+.Dd $Mdocdate: June 12 2020 $
 .Dt PEM_BYTES_READ_BIO 3
 .Os
 .Sh NAME
@@ -86,6 +86,8 @@ The password callback
 and rock
 .Fa u
 are used to obtain the decryption passphrase, if applicable.
+For more details, see
+.Xr pem_password_cb 3 .
 .Pp
 Some data types have compatibility aliases, such as a file containing
 X509 CERTIFICATE matching a request for the deprecated type CERTIFICATE.
@@ -107,7 +109,53 @@ The caller must free the storage pointed to by
 .Sh RETURN VALUES
 .Fn PEM_bytes_read_bio
 returns 1 for success or 0 for failure.
+.Sh ERRORS
+Diagnostics that can be retrieved with
+.Xr ERR_get_error 3 ,
+.Xr ERR_GET_REASON 3 ,
+and
+.Xr ERR_reason_error_string 3
+include:
+.Bl -tag -width Ds
+.It Dv PEM_R_NO_START_LINE Qq no start line
+No more PEM objects were found in the input.
+This can happen when the input contains no PEM objects at all,
+or only objects that do not match the type
+.Fa name .
+.It Dv PEM_R_NOT_PROC_TYPE Qq not proc type
+The first PEM header does not start with
+.Qq "Proc-Type: " .
+.It Dv PEM_R_NOT_ENCRYPTED Qq not encrypted
+The Proc-Type header differs from
+.Qq 4,ENCRYPTED .
+.It Dv PEM_R_SHORT_HEADER Qq short header
+The Proc-Type header is the last header line.
+.It Dv PEM_R_NOT_DEK_INFO Qq not dek info
+The second PEM header does not start with
+.Qq "DEK-Info: " .
+.It Dv PEM_R_UNSUPPORTED_ENCRYPTION Qq unsupported encryption
+The cipher name given in the DEK-Info header is unknown to
+.Xr EVP_get_cipherbyname 3 .
+.It Dv PEM_R_BAD_IV_CHARS Qq "bad iv chars"
+The word following the cipher name in the DEK-Info header
+contains bytes that are not hexadecimal digits.
+This also happens when the initialization vector is missing or too short.
+.It Dv PEM_R_BAD_PASSWORD_READ Qq bad password read
+.Fa cb
+reported failure.
+This may for example happen when the user mistypes the password.
+.It Dv PEM_R_BAD_DECRYPT Qq bad decrypt
+.Xr EVP_DecryptInit_ex 3 ,
+.Xr EVP_DecryptUpdate 3 ,
+or
+.Xr EVP_DecryptFinal_ex 3
+failed.
+.El
+.Pp
+Additional types of errors can result from
+.Xr PEM_read_bio 3 .
 .Sh SEE ALSO
+.Xr PEM_ASN1_read 3 ,
 .Xr PEM_read 3 ,
 .Xr PEM_read_bio_PrivateKey 3
 .Sh HISTORY
diff --git a/src/lib/libcrypto/man/PEM_read.3 b/src/lib/libcrypto/man/PEM_read.3
index 5648aa0145..1469ccd558 100644
--- a/src/lib/libcrypto/man/PEM_read.3
+++ b/src/lib/libcrypto/man/PEM_read.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: PEM_read.3,v 1.9 2019/06/10 14:58:48 schwarze Exp $
+.\"     $OpenBSD: PEM_read.3,v 1.10 2020/06/12 11:37:42 schwarze Exp $
 .\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file was written by Viktor Dukhovni
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 10 2019 $
+.Dd $Mdocdate: June 12 2020 $
 .Dt PEM_READ 3
 .Os
 .Sh NAME
@@ -279,8 +279,11 @@ is likely meaningless if these functions fail.
 .Sh SEE ALSO
 .Xr crypto 3 ,
 .Xr d2i_PKCS8PrivateKey_bio 3 ,
+.Xr PEM_ASN1_read 3 ,
 .Xr PEM_bytes_read_bio 3 ,
 .Xr PEM_read_bio_PrivateKey 3 ,
+.Xr PEM_read_SSL_SESSION 3 ,
+.Xr PEM_write_bio_CMS_stream 3 ,
 .Xr PEM_write_bio_PKCS7_stream 3
 .Sh HISTORY
 .Fn PEM_write ,
diff --git a/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
index cf45356cfa..3799baa040 100644
--- a/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
+++ b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PEM_read_bio_PrivateKey.3,v 1.16 2019/11/02 15:25:34 schwarze Exp $
+.\" $OpenBSD: PEM_read_bio_PrivateKey.3,v 1.17 2020/06/12 11:37:42 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,7 +51,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 2 2019 $
+.Dd $Mdocdate: June 12 2020 $
 .Dt PEM_READ_BIO_PRIVATEKEY 3
 .Os
 .Sh NAME
@@ -770,6 +770,9 @@ will be used to collectively refer to the
 and
 .Fn PEM_write_TYPE
 functions.
+If no set of specific functions exists for a given type,
+.Xr PEM_ASN1_read 3
+can be used instead.
 .Pp
 The
 .Sy PrivateKey
@@ -1266,8 +1269,11 @@ pass_cb(char *buf, int size, int rwflag, void *u)
 .Sh SEE ALSO
 .Xr BIO_new 3 ,
 .Xr DSA_new 3 ,
+.Xr PEM_ASN1_read 3 ,
 .Xr PEM_bytes_read_bio 3 ,
 .Xr PEM_read 3 ,
+.Xr PEM_read_SSL_SESSION 3 ,
+.Xr PEM_write_bio_CMS_stream 3 ,
 .Xr PEM_write_bio_PKCS7_stream 3 ,
 .Xr RSA_new 3 ,
 .Xr X509_CRL_new 3 ,