1.\" $OpenBSD: PEM_ASN1_read.3,v 1.2 2020/07/23 17:34:53 schwarze Exp $ 2.\" 3.\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: July 23 2020 $ 18.Dt PEM_ASN1_READ 3 19.Os 20.Sh NAME 21.Nm d2i_of_void , 22.Nm PEM_ASN1_read , 23.Nm PEM_ASN1_read_bio 24.Nd PEM and DER decode an arbitrary ASN.1 value 25.Sh SYNOPSIS 26.In openssl/pem.h 27.Ft typedef void * 28.Fo d2i_of_void 29.Fa "void **val_out" 30.Fa "const unsigned char **der_in" 31.Fa "long length" 32.Fc 33.Ft void * 34.Fo PEM_ASN1_read 35.Fa "d2i_of_void *d2i" 36.Fa "const char *name" 37.Fa "FILE *in_fp" 38.Fa "void **val_out" 39.Fa "pem_password_cb *cb" 40.Fa "void *u" 41.Fc 42.Ft void * 43.Fo PEM_ASN1_read_bio 44.Fa "d2i_of_void *d2i" 45.Fa "const char *name" 46.Fa "BIO *in_bp" 47.Fa "void **val_out" 48.Fa "pem_password_cb *cb" 49.Fa "void *u" 50.Fc 51.Sh DESCRIPTION 52These functions read one object from 53.Fa in_fp 54or 55.Fa in_bp 56and perform both PEM and DER decoding. 57They are needed when more specific decoding functions 58like those documented in 59.Xr PEM_read_bio_PrivateKey 3 60and 61.Xr PEM_read_SSL_SESSION 3 62are inadequate for the type 63.Fa name . 64.Pp 65For PEM decoding, 66.Xr PEM_bytes_read_bio 3 67is called internally. 68Consequently, the first object of type 69.Fa name 70is returned and preceding objects of other types are discarded. 71If necessary, data is decrypted, using 72.Fa cb 73and/or 74.Fa u 75if they are not 76.Dv NULL , 77as described in the 78.Xr pem_password_cb 3 79manual page. 80.Pp 81For subsequent DER decoding, pass a 82.Fa d2i 83callback function that is adequate for the type 84.Fa name , 85typically returning a pointer of a type more specific than 86.Ft void * . 87For example, 88.Xr d2i_ASN1_TYPE 3 89can always be used and its manual page describes the required 90behaviour of the callback function to be passed. 91Normally, passing a more specific function is more useful; 92candidate functions can be found with 93.Ql man -k Nm~^d2i_ . 94.Pp 95For the 96.Fa name 97argument, the 98.Dv PEM_STRING_* 99string constants defined in 100.In openssl/pem.h 101can be used. 102.Pp 103The 104.Fa val_out 105argument is useless and its many dangers are described in detail in the 106.Xr d2i_ASN1_TYPE 3 107manual page. 108To reduce the risk of bugs, always passing 109.Dv NULL 110is recommended. 111.Sh RETURN VALUES 112These functions return a pointer to the decoded object or 113.Dv NULL 114if an error occurs. 115They fail if 116.Xr PEM_bytes_read_bio 3 117fails, for example because of invalid syntax in the input, an unknown 118encryption, or an invalid passphrase entered by the user. 119They also fail if 120.Fa d2i 121returns 122.Dv NULL , 123for example due to DER decoding errors. 124.Pp 125.Fn PEM_ASN1_read 126may also fail if memory is exhausted. 127.Sh EXAMPLES 128Typical usage of 129.Fn PEM_ASN1_read 130is demonstrated by the implementation of the more specific function 131to PEM and DER decode an X.509 certificate: 132.Bd -literal -offset 2n 133X509 * 134PEM_read_X509(FILE *fp, X509 **val_out, pem_password_cb *cb, void *u) 135{ 136 return PEM_ASN1_read((d2i_of_void *)d2i_X509, PEM_STRING_X509, 137 fp, (void **)val_out, cb, u); 138} 139.Ed 140.Sh ERRORS 141Diagnostics that can be retrieved with 142.Xr ERR_get_error 3 , 143.Xr ERR_GET_REASON 3 , 144and 145.Xr ERR_reason_error_string 3 146include: 147.Bl -tag -width Ds 148.It Dv ERR_R_BUF_LIB Qq "BUF lib" 149.Fn PEM_ASN1_read 150failed to set up a temporary BIO, 151for example because memory was exhausted. 152.It Dv ERR_R_ASN1_LIB Qq "ASN1 lib" 153.Fa d2i 154returned 155.Dv NULL , 156for example due to a DER syntax error. 157.El 158.Pp 159Additional types of errors can result from 160.Xr PEM_bytes_read_bio 3 . 161.Sh SEE ALSO 162.Xr BIO_new 3 , 163.Xr d2i_ASN1_TYPE 3 , 164.Xr PEM_bytes_read_bio 3 , 165.Xr PEM_read 3 , 166.Xr PEM_read_bio_PrivateKey 3 , 167.Xr PEM_read_SSL_SESSION 3 , 168.Xr PEM_X509_INFO_read 3 169.Sh HISTORY 170These functions first appeared in SSLeay 0.5.1 171and have been available since 172.Ox 2.4 . 173