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