From 7df61e79b329ba8e55819ef265e5777895818e4b Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Thu, 23 Jul 2020 17:34:53 +0000 Subject: document PEM_X509_INFO_read(3) and PEM_X509_INFO_read_bio(3) OK tb@ --- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/PEM_ASN1_read.3 | 7 +- src/lib/libcrypto/man/PEM_X509_INFO_read.3 | 187 ++++++++++++++++++++++++ src/lib/libcrypto/man/PEM_bytes_read_bio.3 | 7 +- src/lib/libcrypto/man/PEM_read.3 | 7 +- src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 | 5 +- src/lib/libcrypto/man/X509_INFO_new.3 | 5 +- 7 files changed, 207 insertions(+), 14 deletions(-) create mode 100644 src/lib/libcrypto/man/PEM_X509_INFO_read.3 (limited to 'src') diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 8114f5b96b..0d39580971 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/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 @@ -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/src/lib/libcrypto/man/PEM_ASN1_read.3 b/src/lib/libcrypto/man/PEM_ASN1_read.3 index cea0c2df68..53ebe5ada4 100644 --- a/src/lib/libcrypto/man/PEM_ASN1_read.3 +++ b/src/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 .\" @@ -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/src/lib/libcrypto/man/PEM_X509_INFO_read.3 b/src/lib/libcrypto/man/PEM_X509_INFO_read.3 new file mode 100644 index 0000000000..72658e2b61 --- /dev/null +++ b/src/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 +.\" +.\" 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/src/lib/libcrypto/man/PEM_bytes_read_bio.3 b/src/lib/libcrypto/man/PEM_bytes_read_bio.3 index d1148edfe0..20ad6b8a4d 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.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/src/lib/libcrypto/man/PEM_read.3 b/src/lib/libcrypto/man/PEM_read.3 index 49cdd0f3c5..bbe2b77bd7 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.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/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 index cc58640b1c..89677a7cb3 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.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/src/lib/libcrypto/man/X509_INFO_new.3 b/src/lib/libcrypto/man/X509_INFO_new.3 index 545480e050..9c601ccb03 100644 --- a/src/lib/libcrypto/man/X509_INFO_new.3 +++ b/src/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 .\" .\" 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 -- cgit v1.2.3-55-g6feb