From 2cba49230cf52f81752d62f2b58037520c8f0941 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Fri, 12 Jun 2020 11:37:42 +0000 Subject: document PEM_ASN1_read(3) and PEM_ASN1_read_bio(3); tweaks and OK tb@ --- src/lib/libcrypto/man/PEM_ASN1_read.3 | 171 ++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 src/lib/libcrypto/man/PEM_ASN1_read.3 (limited to 'src/lib/libcrypto/man/PEM_ASN1_read.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 +.\" +.\" 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 . -- cgit v1.2.3-55-g6feb