xref: /openssl/doc/man3/PEM_read.pod (revision 0f84cbc3) 
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-2020 The OpenSSL Project Authors. All Rights Reserved.
126
127Licensed under the Apache License 2.0 (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