1.\" $OpenBSD: PEM_X509_INFO_read.3,v 1.1 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_X509_INFO_READ 3 19.Os 20.Sh NAME 21.Nm PEM_X509_INFO_read , 22.Nm PEM_X509_INFO_read_bio 23.Nd PEM and DER decode X.509 certificates, private keys, and revocation lists 24.Sh SYNOPSIS 25.In openssl/pem.h 26.Ft STACK_OF(X509_INFO) * 27.Fo PEM_X509_INFO_read 28.Fa "FILE *in_fp" 29.Fa "STACK_OF(X509_INFO) *sk" 30.Fa "pem_password_cb *cb" 31.Fa "void *u" 32.Fc 33.Ft STACK_OF(X509_INFO) * 34.Fo PEM_X509_INFO_read_bio 35.Fa "BIO *in_bp" 36.Fa "STACK_OF(X509_INFO) *sk" 37.Fa "pem_password_cb *cb" 38.Fa "void *u" 39.Fc 40.Sh DESCRIPTION 41These functions read zero or more objects 42releated to X.509 certificates from 43.Fa in_fp 44or 45.Fa in_bp , 46perform both PEM and DER decoding, 47and wrap the resulting objects in newly allocated 48.Vt X509_INFO 49containers. 50.Pp 51Setting 52.Fa sk 53to 54.Dv NULL 55is recommended, in which case 56a new stack is allocated, populated, and returned. 57If an existing 58.Fa sk 59is passed in, the created 60.Vt X509_INFO 61objects are pushed onto that stack. 62.Pp 63For PEM decoding, 64.Xr PEM_read_bio 3 65is used internally, implying that any non-PEM data 66before, between, and after the objects is silently discarded. 67.Pp 68For subsequent DER decoding, 69the decoding function and the field of the 70.Vt X509_INFO 71structure to store the new object in 72are selected according to the PEM type name: 73.Bl -column "TRUSTED CERTIFICATE" "d2i_PrivateKey()" "revocation list" 74.It PEM type name Ta decoder Ta Vt X509_INFO No field 75.It CERTIFICATE Ta Xr d2i_X509 3 Ta certificate 76.It X509 CERTIFICATE Ta Xr d2i_X509 3 Ta certificate 77.It TRUSTED CERTIFICATE Ta Xr d2i_X509_AUX 3 Ta certificate 78.It X509 CRL Ta Xr d2i_X509_CRL 3 Ta revocation list 79.It RSA PRIVATE KEY Ta Xr d2i_PrivateKey 3 Ta private key 80.It DSA PRIVATE KEY Ta Xr d2i_PrivateKey 3 Ta private key 81.It EC PRIVATE KEY Ta Xr d2i_PrivateKey 3 Ta private key 82.El 83.Pp 84Whenever the selected field is already occupied, another new 85.Vt X509_INFO 86container is allocated and pushed onto the stack. 87Depending on the sequence of objects in the input, this can result 88in several partially populated 89.Vt X509_INFO 90containers being pushed onto the stack. 91.Pp 92PEM objects of types not listed in the above table are silently skipped. 93.Pp 94Encrypted certificates and revocation lists are decrypted by calling 95.Xr PEM_do_header 3 96internally, passing through the optional arguments 97.Fa cb 98and 99.Fa u . 100Encrypted private keys are not decrypted. 101Instead, the encrypted form is stored as read. 102All the same, 103.Xr PEM_get_EVP_CIPHER_INFO 3 104is called internally to check that PEM headers, if there are any, 105are valid and specify an encryption the library is prepared to handle. 106.Pp 107If any error occurs, objects that had already been read 108during the same call are deleted again and 109.Fa sk 110is left unchanged. 111.Sh RETURN VALUES 112These functions return a pointer to the stack 113the objects read were pushed onto or 114.Dv NULL 115if an error occurs. 116They fail if 117.Xr PEM_read_bio 3 , 118.Xr PEM_get_EVP_CIPHER_INFO 3 , 119.Xr PEM_do_header 3 , 120or DER decoding fails or if memory is exhausted. 121.Sh ERRORS 122Diagnostics that can be retrieved with 123.Xr ERR_get_error 3 , 124.Xr ERR_GET_REASON 3 , 125and 126.Xr ERR_reason_error_string 3 127include: 128.Bl -tag -width Ds 129.It Dv ERR_R_ASN1_LIB Qq "ASN1 lib" 130DER decoding of a PEM object failed. 131.It Dv ERR_R_BUF_LIB Qq BUF lib 132.Fn PEM_X509_INFO_read 133failed to set up a temporary BIO, for example because memory was exhausted. 134.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" 135.Fn PEM_X509_INFO_read_bio 136failed to allocate a new 137.Vt X509_INFO , 138.Vt STACK_OF(X509_INFO) , 139or 140.Vt X509_PKEY 141object. 142.El 143.Pp 144Additional types of errors can result from 145.Xr PEM_read_bio 3 , 146.Xr PEM_get_EVP_CIPHER_INFO 3 , 147and 148.Xr PEM_do_header 3 . 149.Pp 150After these functions failed due to memory exhaustion, 151.Xr ERR_get_error 3 152may sometimes return 0 anyway. 153.Sh SEE ALSO 154.Xr BIO_new 3 , 155.Xr d2i_PrivateKey 3 , 156.Xr d2i_X509 3 , 157.Xr d2i_X509_CRL 3 , 158.Xr EVP_PKEY_new 3 , 159.Xr PEM_read 3 , 160.Xr PEM_read_bio_PrivateKey 3 , 161.Xr STACK_OF 3 , 162.Xr X509_CRL_new 3 , 163.Xr X509_INFO_new 3 , 164.Xr X509_new 3 165.Sh HISTORY 166.Fn PEM_X509_INFO_read 167first appeared in SSLeay 0.5.1 and 168.Fn PEM_X509_INFO_read_bio 169in SSLeay 0.6.0. 170Both functions have been available since 171.Ox 2.4 . 172.Sh CAVEATS 173It is not an error 174if the input does not contain any objects of the desired types. 175In that case, nothing is added to 176.Fa sk , 177or if 178.Fa sk 179is 180.Dv NULL , 181a newly allocated, empty stack is returned. 182The only way to detect this situation is by comparing 183the number of objects on the stack before and after the call. 184.Sh BUGS 185When reaching the end of the input, these functions call 186.Xr ERR_clear_error 3 , 187which may hide errors that occurred before calling these functions. 188