.\" $OpenBSD: PEM_read.3,v 1.15 2023/09/18 15:26:46 schwarze Exp $ .\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 .\" .\" This file is a derived work. .\" The changes are covered by the following Copyright and license: .\" .\" 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. .\" .\" The original file was written by Viktor Dukhovni .\" and by Rich Salz . .\" Copyright (c) 2016 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" 3. All advertising materials mentioning features or use of this .\" software must display the following acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" .\" .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to .\" endorse or promote products derived from this software without .\" prior written permission. For written permission, please contact .\" openssl-core@openssl.org. .\" .\" 5. Products derived from this software may not be called "OpenSSL" .\" nor may "OpenSSL" appear in their names without prior written .\" permission of the OpenSSL Project. .\" .\" 6. Redistributions of any form whatsoever must retain the following .\" acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" .\" .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: September 18 2023 $ .Dt PEM_READ 3 .Os .Sh NAME .Nm PEM_write , .Nm PEM_write_bio , .Nm PEM_read , .Nm PEM_read_bio , .Nm PEM_get_EVP_CIPHER_INFO , .Nm PEM_do_header , .Nm PEM_def_callback , .Nm pem_password_cb .Nd PEM encoding routines .Sh SYNOPSIS .In openssl/pem.h .Ft int .Fo PEM_write .Fa "FILE *fp" .Fa "const char *name" .Fa "const char *header" .Fa "const unsigned char *data" .Fa "long len" .Fc .Ft int .Fo PEM_write_bio .Fa "BIO *bp" .Fa "const char *name" .Fa "const char *header" .Fa "const unsigned char *data" .Fa "long len" .Fc .Ft int .Fo PEM_read .Fa "FILE *fp" .Fa "char **name" .Fa "char **header" .Fa "unsigned char **data" .Fa "long *len" .Fc .Ft int .Fo PEM_read_bio .Fa "BIO *bp" .Fa "char **name" .Fa "char **header" .Fa "unsigned char **data" .Fa "long *len" .Fc .Ft int .Fo PEM_get_EVP_CIPHER_INFO .Fa "char *header" .Fa "EVP_CIPHER_INFO *cinfo" .Fc .Ft int .Fo PEM_do_header .Fa "EVP_CIPHER_INFO *cinfo" .Fa "unsigned char *data" .Fa "long *len" .Fa "pem_password_cb *cb" .Fa "void *userdata" .Fc .Ft int .Fo PEM_def_callback .Fa "char *password" .Fa "int size" .Fa "int verify" .Fa "void *userdata" .Fc .Ft typedef int .Fo pem_password_cb .Fa "char *password" .Fa "int size" .Fa "int verify" .Fa "void *userdata" .Fc .Sh DESCRIPTION These functions read and write PEM-encoded objects, using the PEM type .Fa name , any additional .Fa header information, and the raw .Fa data of length .Fa len . .Pp PEM is the binary content encoding first defined in IETF RFC 1421. The content is a series of base64-encoded lines, surrounded by begin/end markers each on their own line. For example: .Bd -literal -offset indent -----BEGIN PRIVATE KEY----- MIICdg.... \&... bhTQ== -----END PRIVATE KEY----- .Ed .Pp Optional header line(s) may appear after the begin line, and their existence depends on the type of object being written or read. .Pp .Fn PEM_write writes to the file .Fa fp , while .Fn PEM_write_bio writes to the BIO .Fa bp . The .Fa name is the name to use in the marker, the .Fa header is the header value or .Dv NULL , and .Fa data and .Fa len specify the data and its length. .Pp The final .Fa data buffer is typically an ASN.1 object which can be decoded with the .Fn d2i_* function appropriate to the type .Fa name ; see .Xr d2i_X509 3 for examples. .Pp .Fn PEM_read reads from the file .Fa fp , while .Fn PEM_read_bio reads from the BIO .Fa bp . Both skip any non-PEM data that precedes the start of the next PEM object. When an object is successfully retrieved, the type name from the "----BEGIN -----" is returned via the .Fa name argument, any encapsulation headers are returned in .Fa header , and the base64-decoded content and its length are returned via .Fa data and .Fa len , respectively. The .Fa name , .Fa header , and .Fa data pointers should be freed by the caller when no longer needed. .Pp The remaining functions are deprecated because the underlying PEM encryption format is obsolete and should be avoided. It uses an encryption format with an OpenSSL-specific key-derivation function, which employs MD5 with an iteration count of 1. Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5 v2.0 PBE; see .Xr PEM_write_PrivateKey 3 and .Xr d2i_PKCS8PrivateKey_bio 3 . .Pp .Fn PEM_get_EVP_CIPHER_INFO can be used to determine the .Fa data returned by .Fn PEM_read or .Fn PEM_read_bio is encrypted and to retrieve the associated cipher and IV. The caller passes a pointer to a structure of type .Vt EVP_CIPHER_INFO via the .Fa cinfo argument and the .Fa header returned via .Fn PEM_read or .Fn PEM_read_bio . If the call is successful, 1 is returned and the cipher and IV are stored at the address pointed to by .Fa cinfo . When the header is malformed or not supported or when the cipher is unknown or some internal error happens, 0 is returned. .Pp .Fn PEM_do_header can then be used to decrypt the data if the header indicates encryption. The .Fa cinfo argument is a pointer to the structure initialized by a preceding call to .Fn PEM_get_EVP_CIPHER_INFO . If that structure indicates the absence of encryption, .Fn PEM_do_header returns successfully without taking any action. The .Fa data and .Fa len arguments are used both to pass in the encrypted data that was returned in the same arguments from the preceding call to .Fn PEM_read or .Fn PEM_read_bio and to pass out the decrypted data. .Pp The callback function .Fa cb is used to obtain the encryption .Fa password ; if .Fa cb is .Dv NULL , .Fn PEM_def_callback is used instead. The .Fa password buffer needs to be at least .Fa size bytes long. Unless .Fa userdata is .Dv NULL , .Fn PEM_def_callback ignores the .Fa verify argument and copies the NUL-terminated byte string .Fa userdata to .Fa password without a terminating NUL byte, silently truncating the copy to at most .Fa size bytes. If .Fa userdata is .Dv NULL , .Fn PEM_def_callback instead prompts the user for the password with echoing turned off by calling .Xr EVP_read_pw_string_min 3 internally. In this case, the .Fa size is silently reduced to at most .Dv BUFSIZ and at most .Fa size No \- 1 bytes are accepted from the user and copied into the byte string buffer .Fa password . A callback function .Fa cb supplied by the application may use .Fa userdata for a different purpose than .Fn PEM_def_callback does, e.g., as auxiliary data to use while acquiring the password. For example, a GUI application might pass a window handle. If the .Fa verify flag is non-zero, the user is prompted twice for the password to make typos less likely and it is checked that both inputs agree. This flag is not set by .Fn PEM_do_header nor by other read functions, but it is typically set by write functions. .Pp If the data is a priori known to not be encrypted, then neither .Fn PEM_get_EVP_CIPHER_INFO nor .Fn PEM_do_header need to be called. .Sh RETURN VALUES .Fn PEM_read and .Fn PEM_read_bio return 1 on success or 0 on failure. The latter includes the case when no more PEM objects remain in the input file. To distinguish end of file from more serious errors, the caller must peek at the error stack and check for .Dv PEM_R_NO_START_LINE , which indicates that no more PEM objects were found. See .Xr ERR_peek_last_error 3 and .Xr ERR_GET_REASON 3 . .Pp .Fn PEM_get_EVP_CIPHER_INFO and .Fn PEM_do_header return 1 on success or 0 on failure. The .Fa data is likely meaningless if these functions fail. .Pp .Fn PEM_def_callback returns the number of bytes stored into .Fa buf or a negative value on failure, and .Fa cb is expected to behave in the same way. If .Fa userdata is .Dv NULL , .Fn PEM_def_callback fails if .Fa num is less than 5 or if an error occurs trying to prompt the user for the password. Otherwise, it fails when .Fa num is negative. The details of the circumstances that cause .Fa cb to fail may differ. .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 , .Xr PEM_X509_INFO_read 3 .Sh HISTORY .Fn PEM_write , .Fn PEM_read , and .Fn PEM_do_header appeared in SSLeay 0.4 or earlier. .Fn PEM_get_EVP_CIPHER_INFO first appeared in SSLeay 0.5.1. .Fn PEM_write_bio and .Fn PEM_read_bio first appeared in SSLeay 0.6.0. These functions have been available since .Ox 2.4 . .Pp .Fn PEM_def_callback first appeared in OpenSSL 0.9.7 and has been available since .Ox 3.2 .