]>
Commit | Line | Data |
---|---|---|
a29d78e9 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
f097f81c DSH |
5 | PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, |
6 | PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, | |
7 | PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, | |
8 | PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, | |
9 | PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, | |
10 | PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, | |
11 | PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, | |
12 | PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, | |
13 | PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, | |
14 | PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, | |
15 | PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, | |
16 | PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, | |
17 | PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, | |
18 | PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, | |
19 | PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, | |
20 | PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, | |
21 | PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, | |
22 | PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, | |
23 | PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, | |
24 | PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, | |
a0474357 | 25 | PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines |
a29d78e9 DSH |
26 | |
27 | =head1 SYNOPSIS | |
28 | ||
29 | #include <openssl/pem.h> | |
30 | ||
31 | EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, | |
a0474357 | 32 | pem_password_cb *cb, void *u); |
a29d78e9 | 33 | EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, |
a0474357 | 34 | pem_password_cb *cb, void *u); |
a29d78e9 | 35 | int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, |
a0474357 RS |
36 | unsigned char *kstr, int klen, |
37 | pem_password_cb *cb, void *u); | |
a29d78e9 | 38 | int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, |
a0474357 RS |
39 | unsigned char *kstr, int klen, |
40 | pem_password_cb *cb, void *u); | |
a29d78e9 DSH |
41 | |
42 | int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, | |
a0474357 RS |
43 | char *kstr, int klen, |
44 | pem_password_cb *cb, void *u); | |
a29d78e9 | 45 | int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, |
a0474357 RS |
46 | char *kstr, int klen, |
47 | pem_password_cb *cb, void *u); | |
a29d78e9 | 48 | int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid, |
a0474357 RS |
49 | char *kstr, int klen, |
50 | pem_password_cb *cb, void *u); | |
a29d78e9 | 51 | int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid, |
a0474357 RS |
52 | char *kstr, int klen, |
53 | pem_password_cb *cb, void *u); | |
a29d78e9 DSH |
54 | |
55 | EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, | |
a0474357 | 56 | pem_password_cb *cb, void *u); |
a29d78e9 | 57 | EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, |
a0474357 | 58 | pem_password_cb *cb, void *u); |
a29d78e9 DSH |
59 | int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x); |
60 | int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x); | |
61 | ||
62 | RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x, | |
a0474357 | 63 | pem_password_cb *cb, void *u); |
a29d78e9 | 64 | RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, |
a0474357 | 65 | pem_password_cb *cb, void *u); |
a29d78e9 | 66 | int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc, |
a0474357 RS |
67 | unsigned char *kstr, int klen, |
68 | pem_password_cb *cb, void *u); | |
a29d78e9 | 69 | int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, |
a0474357 RS |
70 | unsigned char *kstr, int klen, |
71 | pem_password_cb *cb, void *u); | |
a29d78e9 DSH |
72 | |
73 | RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x, | |
a0474357 | 74 | pem_password_cb *cb, void *u); |
a29d78e9 | 75 | RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, |
a0474357 | 76 | pem_password_cb *cb, void *u); |
a29d78e9 | 77 | int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x); |
a29d78e9 DSH |
78 | int PEM_write_RSAPublicKey(FILE *fp, RSA *x); |
79 | ||
80 | RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x, | |
a0474357 | 81 | pem_password_cb *cb, void *u); |
a29d78e9 | 82 | RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, |
a0474357 | 83 | pem_password_cb *cb, void *u); |
a29d78e9 | 84 | int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x); |
a29d78e9 DSH |
85 | int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x); |
86 | ||
87 | DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x, | |
a0474357 | 88 | pem_password_cb *cb, void *u); |
a29d78e9 | 89 | DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, |
a0474357 | 90 | pem_password_cb *cb, void *u); |
a29d78e9 | 91 | int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc, |
a0474357 RS |
92 | unsigned char *kstr, int klen, |
93 | pem_password_cb *cb, void *u); | |
a29d78e9 | 94 | int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, |
a0474357 RS |
95 | unsigned char *kstr, int klen, |
96 | pem_password_cb *cb, void *u); | |
a29d78e9 DSH |
97 | |
98 | DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x, | |
a0474357 | 99 | pem_password_cb *cb, void *u); |
a29d78e9 | 100 | DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, |
a0474357 | 101 | pem_password_cb *cb, void *u); |
a29d78e9 | 102 | int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x); |
a29d78e9 DSH |
103 | int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x); |
104 | ||
105 | DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u); | |
a29d78e9 | 106 | DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u); |
a29d78e9 | 107 | int PEM_write_bio_DSAparams(BIO *bp, DSA *x); |
a29d78e9 DSH |
108 | int PEM_write_DSAparams(FILE *fp, DSA *x); |
109 | ||
110 | DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u); | |
a29d78e9 | 111 | DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u); |
a29d78e9 | 112 | int PEM_write_bio_DHparams(BIO *bp, DH *x); |
a29d78e9 DSH |
113 | int PEM_write_DHparams(FILE *fp, DH *x); |
114 | ||
115 | X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u); | |
a29d78e9 | 116 | X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u); |
a29d78e9 | 117 | int PEM_write_bio_X509(BIO *bp, X509 *x); |
a29d78e9 DSH |
118 | int PEM_write_X509(FILE *fp, X509 *x); |
119 | ||
120 | X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u); | |
a29d78e9 | 121 | X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u); |
a29d78e9 | 122 | int PEM_write_bio_X509_AUX(BIO *bp, X509 *x); |
a29d78e9 DSH |
123 | int PEM_write_X509_AUX(FILE *fp, X509 *x); |
124 | ||
125 | X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x, | |
a0474357 | 126 | pem_password_cb *cb, void *u); |
a29d78e9 | 127 | X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, |
a0474357 | 128 | pem_password_cb *cb, void *u); |
a29d78e9 | 129 | int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x); |
a29d78e9 | 130 | int PEM_write_X509_REQ(FILE *fp, X509_REQ *x); |
a29d78e9 | 131 | int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x); |
a29d78e9 DSH |
132 | int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x); |
133 | ||
134 | X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x, | |
a0474357 | 135 | pem_password_cb *cb, void *u); |
a29d78e9 | 136 | X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, |
a0474357 | 137 | pem_password_cb *cb, void *u); |
a29d78e9 DSH |
138 | int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x); |
139 | int PEM_write_X509_CRL(FILE *fp, X509_CRL *x); | |
140 | ||
141 | PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u); | |
a29d78e9 | 142 | PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u); |
a29d78e9 | 143 | int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x); |
a29d78e9 DSH |
144 | int PEM_write_PKCS7(FILE *fp, PKCS7 *x); |
145 | ||
a29d78e9 DSH |
146 | =head1 DESCRIPTION |
147 | ||
148 | The PEM functions read or write structures in PEM format. In | |
149 | this sense PEM format is simply base64 encoded data surrounded | |
150 | by header lines. | |
151 | ||
152 | For more details about the meaning of arguments see the | |
153 | B<PEM FUNCTION ARGUMENTS> section. | |
154 | ||
155 | Each operation has four functions associated with it. For | |
156 | clarity the term "B<foobar> functions" will be used to collectively | |
157 | refer to the PEM_read_bio_foobar(), PEM_read_foobar(), | |
158 | PEM_write_bio_foobar() and PEM_write_foobar() functions. | |
159 | ||
160 | The B<PrivateKey> functions read or write a private key in | |
161 | PEM format using an EVP_PKEY structure. The write routines use | |
162 | "traditional" private key format and can handle both RSA and DSA | |
163 | private keys. The read functions can additionally transparently | |
164 | handle PKCS#8 format encrypted and unencrypted keys too. | |
165 | ||
166 | PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() | |
167 | write a private key in an EVP_PKEY structure in PKCS#8 | |
168 | EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption | |
2b4ffc65 | 169 | algorithms. The B<cipher> argument specifies the encryption algorithm to |
a29d78e9 DSH |
170 | use: unlike all other PEM routines the encryption is applied at the |
171 | PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no | |
172 | encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead. | |
173 | ||
174 | PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid() | |
175 | also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however | |
176 | it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm | |
177 | to use is specified in the B<nid> parameter and should be the NID of the | |
178 | corresponding OBJECT IDENTIFIER (see NOTES section). | |
179 | ||
180 | The B<PUBKEY> functions process a public key using an EVP_PKEY | |
181 | structure. The public key is encoded as a SubjectPublicKeyInfo | |
182 | structure. | |
183 | ||
184 | The B<RSAPrivateKey> functions process an RSA private key using an | |
185 | RSA structure. It handles the same formats as the B<PrivateKey> | |
186 | functions but an error occurs if the private key is not RSA. | |
187 | ||
188 | The B<RSAPublicKey> functions process an RSA public key using an | |
189 | RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey | |
190 | structure. | |
191 | ||
192 | The B<RSA_PUBKEY> functions also process an RSA public key using | |
193 | an RSA structure. However the public key is encoded using a | |
194 | SubjectPublicKeyInfo structure and an error occurs if the public | |
195 | key is not RSA. | |
196 | ||
197 | The B<DSAPrivateKey> functions process a DSA private key using a | |
198 | DSA structure. It handles the same formats as the B<PrivateKey> | |
199 | functions but an error occurs if the private key is not DSA. | |
200 | ||
201 | The B<DSA_PUBKEY> functions process a DSA public key using | |
202 | a DSA structure. The public key is encoded using a | |
203 | SubjectPublicKeyInfo structure and an error occurs if the public | |
204 | key is not DSA. | |
205 | ||
206 | The B<DSAparams> functions process DSA parameters using a DSA | |
f097f81c DSH |
207 | structure. The parameters are encoded using a Dss-Parms structure |
208 | as defined in RFC2459. | |
a29d78e9 DSH |
209 | |
210 | The B<DHparams> functions process DH parameters using a DH | |
211 | structure. The parameters are encoded using a PKCS#3 DHparameter | |
212 | structure. | |
213 | ||
214 | The B<X509> functions process an X509 certificate using an X509 | |
215 | structure. They will also process a trusted X509 certificate but | |
216 | any trust settings are discarded. | |
217 | ||
218 | The B<X509_AUX> functions process a trusted X509 certificate using | |
219 | an X509 structure. | |
220 | ||
221 | The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10 | |
222 | certificate request using an X509_REQ structure. The B<X509_REQ> | |
223 | write functions use B<CERTIFICATE REQUEST> in the header whereas | |
224 | the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST> | |
225 | (as required by some CAs). The B<X509_REQ> read functions will | |
226 | handle either form so there are no B<X509_REQ_NEW> read functions. | |
227 | ||
228 | The B<X509_CRL> functions process an X509 CRL using an X509_CRL | |
229 | structure. | |
230 | ||
231 | The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7 | |
232 | structure. | |
233 | ||
a29d78e9 DSH |
234 | =head1 PEM FUNCTION ARGUMENTS |
235 | ||
236 | The PEM functions have many common arguments. | |
237 | ||
238 | The B<bp> BIO parameter (if present) specifies the BIO to read from | |
239 | or write to. | |
240 | ||
241 | The B<fp> FILE parameter (if present) specifies the FILE pointer to | |
242 | read from or write to. | |
243 | ||
244 | The PEM read functions all take an argument B<TYPE **x> and return | |
245 | a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function | |
246 | uses. If B<x> is NULL then the parameter is ignored. If B<x> is not | |
247 | NULL but B<*x> is NULL then the structure returned will be written | |
248 | to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made | |
249 | to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections). | |
250 | Irrespective of the value of B<x> a pointer to the structure is always | |
251 | returned (or NULL if an error occurred). | |
252 | ||
253 | The PEM functions which write private keys take an B<enc> parameter | |
254 | which specifies the encryption algorithm to use, encryption is done | |
255 | at the PEM level. If this parameter is set to NULL then the private | |
256 | key is written in unencrypted form. | |
257 | ||
258 | The B<cb> argument is the callback to use when querying for the pass | |
259 | phrase used for encrypted PEM structures (normally only private keys). | |
260 | ||
261 | For the PEM write routines if the B<kstr> parameter is not NULL then | |
262 | B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is | |
263 | ignored. | |
264 | ||
265 | If the B<cb> parameters is set to NULL and the B<u> parameter is not | |
266 | NULL then the B<u> parameter is interpreted as a null terminated string | |
267 | to use as the passphrase. If both B<cb> and B<u> are NULL then the | |
268 | default callback routine is used which will typically prompt for the | |
269 | passphrase on the current terminal with echoing turned off. | |
270 | ||
271 | The default passphrase callback is sometimes inappropriate (for example | |
272 | in a GUI application) so an alternative can be supplied. The callback | |
273 | routine has the following form: | |
274 | ||
275 | int cb(char *buf, int size, int rwflag, void *u); | |
276 | ||
277 | B<buf> is the buffer to write the passphrase to. B<size> is the maximum | |
278 | length of the passphrase (i.e. the size of buf). B<rwflag> is a flag | |
279 | which is set to 0 when reading and 1 when writing. A typical routine | |
280 | will ask the user to verify the passphrase (for example by prompting | |
281 | for it twice) if B<rwflag> is 1. The B<u> parameter has the same | |
282 | value as the B<u> parameter passed to the PEM routine. It allows | |
283 | arbitrary data to be passed to the callback by the application | |
284 | (for example a window handle in a GUI application). The callback | |
285 | B<must> return the number of characters in the passphrase or 0 if | |
286 | an error occurred. | |
287 | ||
288 | =head1 EXAMPLES | |
289 | ||
290 | Although the PEM routines take several arguments in almost all applications | |
291 | most of them are set to 0 or NULL. | |
292 | ||
293 | Read a certificate in PEM format from a BIO: | |
294 | ||
295 | X509 *x; | |
e88c5777 | 296 | x = PEM_read_bio_X509(bp, NULL, 0, NULL); |
a0474357 RS |
297 | if (x == NULL) { |
298 | /* Error */ | |
299 | } | |
a29d78e9 DSH |
300 | |
301 | Alternative method: | |
302 | ||
303 | X509 *x = NULL; | |
a0474357 RS |
304 | if (!PEM_read_bio_X509(bp, &x, 0, NULL)) { |
305 | /* Error */ | |
306 | } | |
a29d78e9 DSH |
307 | |
308 | Write a certificate to a BIO: | |
309 | ||
a0474357 RS |
310 | if (!PEM_write_bio_X509(bp, x)) { |
311 | /* Error */ | |
312 | } | |
a29d78e9 DSH |
313 | |
314 | Write a private key (using traditional format) to a BIO using | |
315 | triple DES encryption, the pass phrase is prompted for: | |
316 | ||
a0474357 RS |
317 | if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) { |
318 | /* Error */ | |
319 | } | |
a29d78e9 DSH |
320 | |
321 | Write a private key (using PKCS#8 format) to a BIO using triple | |
322 | DES encryption, using the pass phrase "hello": | |
323 | ||
a0474357 RS |
324 | if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) { |
325 | /* Error */ | |
326 | } | |
a29d78e9 DSH |
327 | |
328 | Read a private key from a BIO using a pass phrase callback: | |
329 | ||
330 | key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); | |
a0474357 RS |
331 | if (key == NULL) { |
332 | /* Error */ | |
333 | } | |
a29d78e9 DSH |
334 | |
335 | Skeleton pass phrase callback: | |
336 | ||
a0474357 RS |
337 | int pass_cb(char *buf, int size, int rwflag, void *u) |
338 | { | |
339 | int len; | |
340 | char *tmp; | |
341 | ||
342 | /* We'd probably do something else if 'rwflag' is 1 */ | |
343 | printf("Enter pass phrase for \"%s\"\n", (char *)u); | |
a29d78e9 | 344 | |
a0474357 RS |
345 | /* get pass phrase, length 'len' into 'tmp' */ |
346 | tmp = "hello"; | |
347 | len = strlen(tmp); | |
348 | if (len <= 0) | |
349 | return 0; | |
a29d78e9 | 350 | |
a0474357 RS |
351 | if (len > size) |
352 | len = size; | |
353 | memcpy(buf, tmp, len); | |
354 | return len; | |
355 | } | |
06623ff0 | 356 | |
a29d78e9 DSH |
357 | =head1 NOTES |
358 | ||
359 | The old B<PrivateKey> write routines are retained for compatibility. | |
360 | New applications should write private keys using the | |
361 | PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines | |
362 | because they are more secure (they use an iteration count of 2048 whereas | |
363 | the traditional routines use a count of 1) unless compatibility with older | |
364 | versions of OpenSSL is important. | |
365 | ||
366 | The B<PrivateKey> read routines can be used in all applications because | |
367 | they handle all formats transparently. | |
368 | ||
369 | A frequent cause of problems is attempting to use the PEM routines like | |
370 | this: | |
371 | ||
372 | X509 *x; | |
373 | PEM_read_bio_X509(bp, &x, 0, NULL); | |
374 | ||
375 | this is a bug because an attempt will be made to reuse the data at B<x> | |
376 | which is an uninitialised pointer. | |
377 | ||
06623ff0 DSH |
378 | =head1 PEM ENCRYPTION FORMAT |
379 | ||
a0474357 | 380 | These old B<PrivateKey> routines use a non standard technique for encryption. |
06623ff0 DSH |
381 | |
382 | The private key (or other data) takes the following form: | |
383 | ||
384 | -----BEGIN RSA PRIVATE KEY----- | |
385 | Proc-Type: 4,ENCRYPTED | |
386 | DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 | |
387 | ||
388 | ...base64 encoded data... | |
389 | -----END RSA PRIVATE KEY----- | |
390 | ||
a0474357 RS |
391 | The line beginning with I<Proc-Type> contains the version and the |
392 | protection on the encapsulated data. The line beginning I<DEK-Info> | |
393 | contains two comma separated values: the encryption algorithm name as | |
394 | used by EVP_get_cipherbyname() and an initialization vector used by the | |
395 | cipher encoded as a set of hexadecimal digits. After those two lines is | |
396 | the base64-encoded encrypted data. | |
06623ff0 | 397 | |
a0474357 RS |
398 | The encryption key is derived using EVP_BytesToKey(). The cipher's |
399 | initialization vector is passed to EVP_BytesToKey() as the B<salt> | |
400 | parameter. Internally, B<PKCS5_SALT_LEN> bytes of the salt are used | |
401 | (regardless of the size of the initialization vector). The user's | |
b9b6a7e5 | 402 | password is passed to EVP_BytesToKey() using the B<data> and B<datal> |
a0474357 RS |
403 | parameters. Finally, the library uses an iteration count of 1 for |
404 | EVP_BytesToKey(). | |
06623ff0 | 405 | |
a0474357 RS |
406 | he B<key> derived by EVP_BytesToKey() along with the original initialization |
407 | vector is then used to decrypt the encrypted data. The B<iv> produced by | |
408 | EVP_BytesToKey() is not utilized or needed, and NULL should be passed to | |
409 | the function. | |
410 | ||
411 | The pseudo code to derive the key would look similar to: | |
412 | ||
413 | EVP_CIPHER* cipher = EVP_des_ede3_cbc(); | |
414 | EVP_MD* md = EVP_md5(); | |
415 | ||
416 | unsigned int nkey = EVP_CIPHER_key_length(cipher); | |
417 | unsigned int niv = EVP_CIPHER_iv_length(cipher); | |
418 | unsigned char key[nkey]; | |
419 | unsigned char iv[niv]; | |
420 | ||
421 | memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv); | |
422 | rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/); | |
423 | if (rc != nkey) { | |
424 | /* Error */ | |
425 | } | |
426 | ||
427 | /* On success, use key and iv to initialize the cipher */ | |
06623ff0 | 428 | |
a29d78e9 DSH |
429 | =head1 BUGS |
430 | ||
431 | The PEM read routines in some versions of OpenSSL will not correctly reuse | |
432 | an existing structure. Therefore the following: | |
433 | ||
e88c5777 | 434 | PEM_read_bio_X509(bp, &x, 0, NULL); |
a29d78e9 DSH |
435 | |
436 | where B<x> already contains a valid certificate, may not work, whereas: | |
437 | ||
438 | X509_free(x); | |
e88c5777 | 439 | x = PEM_read_bio_X509(bp, NULL, 0, NULL); |
a29d78e9 DSH |
440 | |
441 | is guaranteed to work. | |
442 | ||
443 | =head1 RETURN CODES | |
444 | ||
445 | The read routines return either a pointer to the structure read or NULL | |
9449e385 | 446 | if an error occurred. |
a29d78e9 DSH |
447 | |
448 | The write routines return 1 for success or 0 for failure. | |
d48e78f0 | 449 | |
a0474357 RS |
450 | =head1 HISTORY |
451 | ||
452 | The old Netscape certificate sequences were no longer documented | |
453 | in OpenSSL 1.1; applications should use the PKCS7 standard instead | |
454 | as they will be formally deprecated in a future releases. | |
455 | ||
d48e78f0 JW |
456 | =head1 SEE ALSO |
457 | ||
a0474357 | 458 | L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)> |
99ec4fdb RS |
459 | |
460 | =cut | |
e2f92610 RS |
461 | |
462 | =head1 COPYRIGHT | |
463 | ||
464 | Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. | |
465 | ||
466 | Licensed under the OpenSSL license (the "License"). You may not use | |
467 | this file except in compliance with the License. You can obtain a copy | |
468 | in the file LICENSE in the source distribution or at | |
469 | L<https://www.openssl.org/source/license.html>. | |
470 | ||
471 | =cut |