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