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