document PEM_X509_INFO_read(3) and PEM_X509_INFO_read_bio(3)

OK tb@

7 files changed, 207 insertions, 14 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 8114f5b96ba..0d39580971b 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.170 2020/06/24 17:00:38 schwarze Exp $
+# $OpenBSD: Makefile,v 1.171 2020/07/23 17:34:53 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -206,6 +206,7 @@ MAN=	\
 	OPENSSL_sk_new.3 \
 	OpenSSL_add_all_algorithms.3 \
 	PEM_ASN1_read.3 \
+	PEM_X509_INFO_read.3 \
 	PEM_bytes_read_bio.3 \
 	PEM_read.3 \
 	PEM_read_bio_PrivateKey.3 \
diff --git a/lib/libcrypto/man/PEM_ASN1_read.3 b/lib/libcrypto/man/PEM_ASN1_read.3
index cea0c2df684..53ebe5ada42 100644
--- a/lib/libcrypto/man/PEM_ASN1_read.3
+++ b/lib/libcrypto/man/PEM_ASN1_read.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PEM_ASN1_read.3,v 1.1 2020/06/12 11:37:42 schwarze Exp $
+.\" $OpenBSD: PEM_ASN1_read.3,v 1.2 2020/07/23 17:34:53 schwarze Exp $
 .\"
 .\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 $
+.Dd $Mdocdate: July 23 2020 $
 .Dt PEM_ASN1_READ 3
 .Os
 .Sh NAME
@@ -164,7 +164,8 @@ Additional types of errors can result from
 .Xr PEM_bytes_read_bio 3 ,
 .Xr PEM_read 3 ,
 .Xr PEM_read_bio_PrivateKey 3 ,
-.Xr PEM_read_SSL_SESSION 3
+.Xr PEM_read_SSL_SESSION 3 ,
+.Xr PEM_X509_INFO_read 3
 .Sh HISTORY
 These functions first appeared in SSLeay 0.5.1
 and have been available since
diff --git a/lib/libcrypto/man/PEM_X509_INFO_read.3 b/lib/libcrypto/man/PEM_X509_INFO_read.3
new file mode 100644
index 00000000000..72658e2b610
--- /dev/null
+++ b/lib/libcrypto/man/PEM_X509_INFO_read.3
@@ -0,0 +1,187 @@
+.\" $OpenBSD: PEM_X509_INFO_read.3,v 1.1 2020/07/23 17:34:53 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: July 23 2020 $
+.Dt PEM_X509_INFO_READ 3
+.Os
+.Sh NAME
+.Nm PEM_X509_INFO_read ,
+.Nm PEM_X509_INFO_read_bio
+.Nd PEM and DER decode X.509 certificates, private keys, and revocation lists
+.Sh SYNOPSIS
+.In openssl/pem.h
+.Ft STACK_OF(X509_INFO) *
+.Fo PEM_X509_INFO_read
+.Fa "FILE *in_fp"
+.Fa "STACK_OF(X509_INFO) *sk"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft STACK_OF(X509_INFO) *
+.Fo PEM_X509_INFO_read_bio
+.Fa "BIO *in_bp"
+.Fa "STACK_OF(X509_INFO) *sk"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Sh DESCRIPTION
+These functions read zero or more objects
+releated to X.509 certificates from
+.Fa in_fp
+or
+.Fa in_bp ,
+perform both PEM and DER decoding,
+and wrap the resulting objects in newly allocated
+.Vt X509_INFO
+containers.
+.Pp
+Setting
+.Fa sk
+to
+.Dv NULL
+is recommended, in which case
+a new stack is allocated, populated, and returned.
+If an existing
+.Fa sk
+is passed in, the created
+.Vt X509_INFO
+objects are pushed onto that stack.
+.Pp
+For PEM decoding,
+.Xr PEM_read_bio 3
+is used internally, implying that any non-PEM data
+before, between, and after the objects is silently discarded.
+.Pp
+For subsequent DER decoding,
+the decoding function and the field of the
+.Vt X509_INFO
+structure to store the new object in
+are selected according to the PEM type name:
+.Bl -column "TRUSTED CERTIFICATE" "d2i_PrivateKey()" "revocation list"
+.It PEM type name       Ta decoder             Ta Vt X509_INFO No field
+.It CERTIFICATE         Ta Xr d2i_X509 3       Ta certificate
+.It X509 CERTIFICATE    Ta Xr d2i_X509 3       Ta certificate
+.It TRUSTED CERTIFICATE Ta Xr d2i_X509_AUX 3   Ta certificate
+.It X509 CRL            Ta Xr d2i_X509_CRL 3   Ta revocation list
+.It RSA PRIVATE KEY     Ta Xr d2i_PrivateKey 3 Ta private key
+.It DSA PRIVATE KEY     Ta Xr d2i_PrivateKey 3 Ta private key
+.It EC PRIVATE KEY      Ta Xr d2i_PrivateKey 3 Ta private key
+.El
+.Pp
+Whenever the selected field is already occupied, another new
+.Vt X509_INFO
+container is allocated and pushed onto the stack.
+Depending on the sequence of objects in the input, this can result
+in several partially populated
+.Vt X509_INFO
+containers being pushed onto the stack.
+.Pp
+PEM objects of types not listed in the above table are silently skipped.
+.Pp
+Encrypted certificates and revocation lists are decrypted by calling
+.Xr PEM_do_header 3
+internally, passing through the optional arguments
+.Fa cb
+and
+.Fa u .
+Encrypted private keys are not decrypted.
+Instead, the encrypted form is stored as read.
+All the same,
+.Xr PEM_get_EVP_CIPHER_INFO 3
+is called internally to check that PEM headers, if there are any,
+are valid and specify an encryption the library is prepared to handle.
+.Pp
+If any error occurs, objects that had already been read
+during the same call are deleted again and
+.Fa sk
+is left unchanged.
+.Sh RETURN VALUES
+These functions return a pointer to the stack
+the objects read were pushed onto or
+.Dv NULL
+if an error occurs.
+They fail if
+.Xr PEM_read_bio 3 ,
+.Xr PEM_get_EVP_CIPHER_INFO 3 ,
+.Xr PEM_do_header 3 ,
+or DER decoding fails or if memory is exhausted.
+.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_ASN1_LIB Qq "ASN1 lib"
+DER decoding of a PEM object failed.
+.It Dv ERR_R_BUF_LIB Qq BUF lib
+.Fn PEM_X509_INFO_read
+failed to set up a temporary BIO, for example because memory was exhausted.
+.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure"
+.Fn PEM_X509_INFO_read_bio
+failed to allocate a new
+.Vt X509_INFO ,
+.Vt STACK_OF(X509_INFO) ,
+or
+.Vt X509_PKEY
+object.
+.El
+.Pp
+Additional types of errors can result from
+.Xr PEM_read_bio 3 ,
+.Xr PEM_get_EVP_CIPHER_INFO 3 ,
+and
+.Xr PEM_do_header 3 .
+.Pp
+After these functions failed due to memory exhaustion,
+.Xr ERR_get_error 3
+may sometimes return 0 anyway.
+.Sh SEE ALSO
+.Xr BIO_new 3 ,
+.Xr d2i_PrivateKey 3 ,
+.Xr d2i_X509 3 ,
+.Xr d2i_X509_CRL 3 ,
+.Xr EVP_PKEY_new 3 ,
+.Xr PEM_read 3 ,
+.Xr PEM_read_bio_PrivateKey 3 ,
+.Xr STACK_OF 3 ,
+.Xr X509_CRL_new 3 ,
+.Xr X509_INFO_new 3 ,
+.Xr X509_new 3
+.Sh HISTORY
+.Fn PEM_X509_INFO_read
+first appeared in SSLeay 0.5.1 and
+.Fn PEM_X509_INFO_read_bio
+in SSLeay 0.6.0.
+Both functions have been available since
+.Ox 2.4 .
+.Sh CAVEATS
+It is not an error
+if the input does not contain any objects of the desired types.
+In that case, nothing is added to
+.Fa sk ,
+or if
+.Fa sk
+is
+.Dv NULL ,
+a newly allocated, empty stack is returned.
+The only way to detect this situation is by comparing
+the number of objects on the stack before and after the call.
+.Sh BUGS
+When reaching the end of the input, these functions call
+.Xr ERR_clear_error 3 ,
+which may hide errors that occurred before calling these functions.
diff --git a/lib/libcrypto/man/PEM_bytes_read_bio.3 b/lib/libcrypto/man/PEM_bytes_read_bio.3
index d1148edfe0e..20ad6b8a4d1 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.5 2020/06/15 14:13:14 schwarze Exp $
+.\" $OpenBSD: PEM_bytes_read_bio.3,v 1.6 2020/07/23 17:34:53 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 15 2020 $
+.Dd $Mdocdate: July 23 2020 $
 .Dt PEM_BYTES_READ_BIO 3
 .Os
 .Sh NAME
@@ -174,7 +174,8 @@ Additional types of errors can result from
 .Sh SEE ALSO
 .Xr PEM_ASN1_read 3 ,
 .Xr PEM_read 3 ,
-.Xr PEM_read_bio_PrivateKey 3
+.Xr PEM_read_bio_PrivateKey 3 ,
+.Xr PEM_X509_INFO_read 3
 .Sh STANDARDS
 RFC 1421: Privacy Enhancement for Internet Electronic Mail (PEM), Part I
 .Sh HISTORY
diff --git a/lib/libcrypto/man/PEM_read.3 b/lib/libcrypto/man/PEM_read.3
index 49cdd0f3c5b..bbe2b77bd75 100644
--- a/lib/libcrypto/man/PEM_read.3
+++ b/lib/libcrypto/man/PEM_read.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PEM_read.3,v 1.11 2020/06/15 14:13:14 schwarze Exp $
+.\" $OpenBSD: PEM_read.3,v 1.12 2020/07/23 17:34:53 schwarze Exp $
 .\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100
 .\"
 .\" This file is a derived work.
@@ -66,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 15 2020 $
+.Dd $Mdocdate: July 23 2020 $
 .Dt PEM_READ 3
 .Os
 .Sh NAME
@@ -388,7 +388,8 @@ to fail may differ.
 .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
+.Xr PEM_write_bio_PKCS7_stream 3 ,
+.Xr PEM_X509_INFO_read 3
 .Sh HISTORY
 .Fn PEM_write ,
 .Fn PEM_read ,
diff --git a/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 b/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
index cc58640b1c9..89677a7cb3c 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.18 2020/06/15 14:13:14 schwarze Exp $
+.\" $OpenBSD: PEM_read_bio_PrivateKey.3,v 1.19 2020/07/23 17:34:53 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: June 15 2020 $
+.Dd $Mdocdate: July 23 2020 $
 .Dt PEM_READ_BIO_PRIVATEKEY 3
 .Os
 .Sh NAME
@@ -1217,6 +1217,7 @@ pass_cb(char *buf, int size, int rwflag, void *u)
 .Xr PEM_read_SSL_SESSION 3 ,
 .Xr PEM_write_bio_CMS_stream 3 ,
 .Xr PEM_write_bio_PKCS7_stream 3 ,
+.Xr PEM_X509_INFO_read 3 ,
 .Xr RSA_new 3 ,
 .Xr X509_CRL_new 3 ,
 .Xr X509_REQ_new 3 ,
diff --git a/lib/libcrypto/man/X509_INFO_new.3 b/lib/libcrypto/man/X509_INFO_new.3
index 545480e050a..9c601ccb03f 100644
--- a/lib/libcrypto/man/X509_INFO_new.3
+++ b/lib/libcrypto/man/X509_INFO_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_INFO_new.3,v 1.1 2019/08/19 13:52:53 schwarze Exp $
+.\" $OpenBSD: X509_INFO_new.3,v 1.2 2020/07/23 17:34:53 schwarze Exp $
 .\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
@@ -13,7 +13,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: August 19 2019 $
+.Dd $Mdocdate: July 23 2020 $
 .Dt X509_INFO_NEW 3
 .Os
 .Sh NAME
@@ -60,6 +60,7 @@ object or
 .Dv NULL
 if an error occurs.
 .Sh SEE ALSO
+.Xr PEM_X509_INFO_read 3 ,
 .Xr X509_CRL_new 3 ,
 .Xr X509_new 3
 .Sh HISTORY