From 0bce9751943e4ed359b05bb17d9cec8d3a36da59 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Fri, 12 Jun 2020 11:37:42 +0000 Subject: [PATCH 20/87] document PEM_ASN1_read(3) and PEM_ASN1_read_bio(3); tweaks and OK tb@ --- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/PEM_ASN1_read.3 | 171 ++++++++++++++++++ src/lib/libcrypto/man/PEM_bytes_read_bio.3 | 52 +++++- src/lib/libcrypto/man/PEM_read.3 | 7 +- .../libcrypto/man/PEM_read_bio_PrivateKey.3 | 10 +- 5 files changed, 236 insertions(+), 7 deletions(-) create mode 100644 src/lib/libcrypto/man/PEM_ASN1_read.3 diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 05b1a54c8..c613fdc29 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 @@ -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 000000000..cea0c2df6 --- /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 +.\" +.\" 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 b3cb143cf..63b8a58d9 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 . @@ -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 5648aa014..1469ccd55 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 cf45356cf..3799baa04 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 , -- 2.17.1