1=pod 2 3=head1 NAME 4 5PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO, PEM_write, 6PEM_write_bio, PEM_ASN1_write, PEM_ASN1_write_bio, PEM_ASN1_write_bio_ctx 7- PEM encoding routines 8 9=head1 SYNOPSIS 10 11 #include <openssl/pem.h> 12 13 int PEM_read(FILE *fp, char **name, char **header, 14 unsigned char **data, long *len); 15 int PEM_read_bio(BIO *bp, char **name, char **header, 16 unsigned char **data, long *len); 17 18 int PEM_get_EVP_CIPHER_INFO(char *header, EVP_CIPHER_INFO *cinfo); 19 int PEM_do_header(EVP_CIPHER_INFO *cinfo, unsigned char *data, long *len, 20 pem_password_cb *cb, void *u); 21 22 int PEM_write(FILE *fp, const char *name, const char *header, 23 const unsigned char *data, long len); 24 int PEM_write_bio(BIO *bp, const char *name, const char *header, 25 const unsigned char *data, long len); 26 int PEM_ASN1_write(i2d_of_void *i2d, const char *name, FILE *fp, 27 const void *x, const EVP_CIPHER *enc, 28 const unsigned char *kstr, int klen, 29 pem_password_cb *callback, void *u); 30 int PEM_ASN1_write_bio(i2d_of_void *i2d, const char *name, BIO *bp, 31 const void *x, const EVP_CIPHER *enc, 32 const unsigned char *kstr, int klen, 33 pem_password_cb *callback, void *u); 34 int PEM_ASN1_write_bio_ctx(OSSL_i2d_of_void_ctx *i2d, void *vctx, 35 const char *name, BIO *bp, const void *x, 36 const EVP_CIPHER *enc, const unsigned char *kstr, 37 int klen, pem_password_cb *callback, void *u); 38 39=head1 DESCRIPTION 40 41These functions read and write PEM-encoded objects, using the PEM 42type B<name>, any additional B<header> information, and the raw 43B<data> of length B<len>. 44 45PEM is the term used for binary content encoding first defined in IETF 46RFC 1421. The content is a series of base64-encoded lines, surrounded 47by begin/end markers each on their own line. For example: 48 49 -----BEGIN PRIVATE KEY----- 50 MIICdg.... 51 ... bhTQ== 52 -----END PRIVATE KEY----- 53 54Optional header line(s) may appear after the begin line, and their 55existence depends on the type of object being written or read. 56 57PEM_write() writes to the file B<fp>, while PEM_write_bio() writes to 58the BIO B<bp>. The B<name> is the name to use in the marker, the 59B<header> is the header value or NULL, and B<data> and B<len> specify 60the data and its length. 61 62The final B<data> buffer is typically an ASN.1 object which can be decoded with 63the B<d2i> function appropriate to the type B<name>; see L<d2i_X509(3)> 64for examples. 65 66PEM_read() reads from the file B<fp>, while PEM_read_bio() reads 67from the BIO B<bp>. 68Both skip any non-PEM data that precedes the start of the next PEM object. 69When an object is successfully retrieved, the type name from the "----BEGIN 70<type>-----" is returned via the B<name> argument, any encapsulation headers 71are returned in B<header> and the base64-decoded content and its length are 72returned via B<data> and B<len> respectively. 73The B<name>, B<header> and B<data> pointers are allocated via OPENSSL_malloc() 74and should be freed by the caller via OPENSSL_free() when no longer needed. 75 76PEM_get_EVP_CIPHER_INFO() can be used to determine the B<data> returned by 77PEM_read() or PEM_read_bio() is encrypted and to retrieve the associated cipher 78and IV. 79The caller passes a pointer to structure of type B<EVP_CIPHER_INFO> via the 80B<cinfo> argument and the B<header> returned via PEM_read() or PEM_read_bio(). 81If the call is successful 1 is returned and the cipher and IV are stored at the 82address pointed to by B<cinfo>. 83When the header is malformed, or not supported or when the cipher is unknown 84or some internal error happens 0 is returned. 85This function is deprecated, see B<NOTES> below. 86 87PEM_do_header() can then be used to decrypt the data if the header 88indicates encryption. 89The B<cinfo> argument is a pointer to the structure initialized by the previous 90call to PEM_get_EVP_CIPHER_INFO(). 91The B<data> and B<len> arguments are those returned by the previous call to 92PEM_read() or PEM_read_bio(). 93The B<cb> and B<u> arguments make it possible to override the default password 94prompt function as described in L<PEM_read_PrivateKey(3)>. 95On successful completion the B<data> is decrypted in place, and B<len> is 96updated to indicate the plaintext length. 97This function is deprecated, see B<NOTES> below. 98 99If the data is a priori known to not be encrypted, then neither PEM_do_header() 100nor PEM_get_EVP_CIPHER_INFO() need be called. 101 102=head1 RETURN VALUES 103 104PEM_read(), and PEM_read_bio() return 1 on success and 0 on failure, the latter 105includes the case when no more PEM objects remain in the input file. To 106distinguish end of file from more serious errors the caller must peek at the 107error stack and check for B<PEM_R_NO_START_LINE>, which indicates that no more 108PEM objects were found. See L<ERR_peek_last_error(3)>, L<ERR_GET_REASON(3)>. 109 110PEM_get_EVP_CIPHER_INFO() and PEM_do_header() return 1 on success, and 0 on 111failure. 112The B<data> is likely meaningless if these functions fail. 113 114=head1 NOTES 115 116The PEM_get_EVP_CIPHER_INFO() and PEM_do_header() functions are deprecated. 117This is because the underlying PEM encryption format is obsolete, and should 118be avoided. 119It uses an encryption format with an OpenSSL-specific key-derivation function, 120which employs MD5 with an iteration count of 1! 121Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5 122v2.0 PBE. 123See L<PEM_write_PrivateKey(3)> and L<d2i_PKCS8PrivateKey_bio(3)>. 124 125PEM_do_header() makes no assumption regarding the pass phrase received from the 126password callback. 127It will simply be treated as a byte sequence. 128 129PEM_write() and PEM_write_bio() return the number of encoded bytes (not 130counting the PEM header and end marker) written on success or 0 on failure. 131 132PEM_ASN1_write_bio(), and PEM_ASN1_write_bio_ctx() return 1 on success and 0 on 133failure. The latter function passes an additional application-provided context 134value to the B<i2d> function that serialises the input ASN.1 object. 135 136=head1 SEE ALSO 137 138L<ERR_peek_last_error(3)>, L<ERR_GET_LIB(3)>, 139L<d2i_PKCS8PrivateKey_bio(3)>, 140L<passphrase-encoding(7)> 141 142=head1 HISTORY 143 144The PEM_ASN1_write_bio_ctx() function was added in OpenSSL 3.5. 145 146=head1 COPYRIGHT 147 148Copyright 1998-2025 The OpenSSL Project Authors. All Rights Reserved. 149 150Licensed under the Apache License 2.0 (the "License"). You may not use 151this file except in compliance with the License. You can obtain a copy 152in the file LICENSE in the source distribution or at 153L<https://www.openssl.org/source/license.html>. 154 155=cut 156