pem.pod revision 279265 
1=pod
2
3=head1 NAME
4
5PEM, 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
183The PEM functions read or write structures in PEM format. In
184this sense PEM format is simply base64 encoded data surrounded
185by header lines.
186
187For more details about the meaning of arguments see the
188B<PEM FUNCTION ARGUMENTS> section.
189
190Each operation has four functions associated with it. For
191clarity the term "B<foobar> functions" will be used to collectively
192refer to the PEM_read_bio_foobar(), PEM_read_foobar(),
193PEM_write_bio_foobar() and PEM_write_foobar() functions.
194
195The B<PrivateKey> functions read or write a private key in
196PEM format using an EVP_PKEY structure. The write routines use
197"traditional" private key format and can handle both RSA and DSA
198private keys. The read functions can additionally transparently
199handle PKCS#8 format encrypted and unencrypted keys too.
200
201PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey()
202write a private key in an EVP_PKEY structure in PKCS#8
203EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption
204algorithms. The B<cipher> argument specifies the encryption algoritm to
205use: unlike all other PEM routines the encryption is applied at the
206PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no
207encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead.
208
209PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
210also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
211it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
212to use is specified in the B<nid> parameter and should be the NID of the
213corresponding OBJECT IDENTIFIER (see NOTES section).
214
215The B<PUBKEY> functions process a public key using an EVP_PKEY
216structure. The public key is encoded as a SubjectPublicKeyInfo
217structure.
218
219The B<RSAPrivateKey> functions process an RSA private key using an
220RSA structure. It handles the same formats as the B<PrivateKey>
221functions but an error occurs if the private key is not RSA.
222
223The B<RSAPublicKey> functions process an RSA public key using an
224RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey
225structure.
226
227The B<RSA_PUBKEY> functions also process an RSA public key using
228an RSA structure. However the public key is encoded using a
229SubjectPublicKeyInfo structure and an error occurs if the public
230key is not RSA.
231
232The B<DSAPrivateKey> functions process a DSA private key using a
233DSA structure. It handles the same formats as the B<PrivateKey>
234functions but an error occurs if the private key is not DSA.
235
236The B<DSA_PUBKEY> functions process a DSA public key using
237a DSA structure. The public key is encoded using a
238SubjectPublicKeyInfo structure and an error occurs if the public
239key is not DSA.
240
241The B<DSAparams> functions process DSA parameters using a DSA
242structure. The parameters are encoded using a foobar structure.
243
244The B<DHparams> functions process DH parameters using a DH
245structure. The parameters are encoded using a PKCS#3 DHparameter
246structure.
247
248The B<X509> functions process an X509 certificate using an X509
249structure. They will also process a trusted X509 certificate but
250any trust settings are discarded.
251
252The B<X509_AUX> functions process a trusted X509 certificate using
253an X509 structure. 
254
255The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10
256certificate request using an X509_REQ structure. The B<X509_REQ>
257write functions use B<CERTIFICATE REQUEST> in the header whereas
258the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST>
259(as required by some CAs). The B<X509_REQ> read functions will
260handle either form so there are no B<X509_REQ_NEW> read functions.
261
262The B<X509_CRL> functions process an X509 CRL using an X509_CRL
263structure.
264
265The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7
266structure.
267
268The B<NETSCAPE_CERT_SEQUENCE> functions process a Netscape Certificate
269Sequence using a NETSCAPE_CERT_SEQUENCE structure.
270
271=head1 PEM FUNCTION ARGUMENTS
272
273The PEM functions have many common arguments.
274
275The B<bp> BIO parameter (if present) specifies the BIO to read from
276or write to.
277
278The B<fp> FILE parameter (if present) specifies the FILE pointer to
279read from or write to.
280
281The PEM read functions all take an argument B<TYPE **x> and return
282a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function
283uses. If B<x> is NULL then the parameter is ignored. If B<x> is not
284NULL but B<*x> is NULL then the structure returned will be written
285to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made
286to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections).
287Irrespective of the value of B<x> a pointer to the structure is always
288returned (or NULL if an error occurred).
289
290The PEM functions which write private keys take an B<enc> parameter
291which specifies the encryption algorithm to use, encryption is done
292at the PEM level. If this parameter is set to NULL then the private
293key is written in unencrypted form.
294
295The B<cb> argument is the callback to use when querying for the pass
296phrase used for encrypted PEM structures (normally only private keys).
297
298For the PEM write routines if the B<kstr> parameter is not NULL then
299B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is
300ignored.
301
302If the B<cb> parameters is set to NULL and the B<u> parameter is not
303NULL then the B<u> parameter is interpreted as a null terminated string
304to use as the passphrase. If both B<cb> and B<u> are NULL then the
305default callback routine is used which will typically prompt for the
306passphrase on the current terminal with echoing turned off.
307
308The default passphrase callback is sometimes inappropriate (for example
309in a GUI application) so an alternative can be supplied. The callback
310routine has the following form:
311
312 int cb(char *buf, int size, int rwflag, void *u);
313
314B<buf> is the buffer to write the passphrase to. B<size> is the maximum
315length of the passphrase (i.e. the size of buf). B<rwflag> is a flag
316which is set to 0 when reading and 1 when writing. A typical routine
317will ask the user to verify the passphrase (for example by prompting
318for it twice) if B<rwflag> is 1. The B<u> parameter has the same
319value as the B<u> parameter passed to the PEM routine. It allows
320arbitrary data to be passed to the callback by the application
321(for example a window handle in a GUI application). The callback
322B<must> return the number of characters in the passphrase or 0 if
323an error occurred.
324
325=head1 EXAMPLES
326
327Although the PEM routines take several arguments in almost all applications
328most of them are set to 0 or NULL.
329
330Read 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
339Alternative method:
340
341 X509 *x = NULL;
342 if (!PEM_read_bio_X509(bp, &x, 0, NULL))
343	{
344	/* Error */
345	}
346
347Write a certificate to a BIO:
348
349 if (!PEM_write_bio_X509(bp, x))
350	{
351	/* Error */
352	}
353
354Write 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
361Write a private key (using traditional format) to a BIO using
362triple 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
369Write a private key (using PKCS#8 format) to a BIO using triple
370DES 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
377Read 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
385Read 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
393Skeleton 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
415The old B<PrivateKey> write routines are retained for compatibility.
416New applications should write private keys using the
417PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
418because they are more secure (they use an iteration count of 2048 whereas
419the traditional routines use a count of 1) unless compatibility with older
420versions of OpenSSL is important.
421
422The B<PrivateKey> read routines can be used in all applications because
423they handle all formats transparently.
424
425A frequent cause of problems is attempting to use the PEM routines like
426this:
427
428 X509 *x;
429 PEM_read_bio_X509(bp, &x, 0, NULL);
430
431this is a bug because an attempt will be made to reuse the data at B<x>
432which is an uninitialised pointer.
433
434=head1 PEM ENCRYPTION FORMAT
435
436This old B<PrivateKey> routines use a non standard technique for encryption.
437
438The 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
447The line beginning DEK-Info contains two comma separated pieces of information:
448the encryption algorithm name as used by EVP_get_cipherbyname() and an 8
449byte B<salt> encoded as a set of hexadecimal digits.
450
451After this is the base64 encoded encrypted data.
452
453The encryption key is determined using EVP_BytesToKey(), using B<salt> and an
454iteration count of 1. The IV used is the value of B<salt> and *not* the IV
455returned by EVP_BytesToKey().
456
457=head1 BUGS
458
459The PEM read routines in some versions of OpenSSL will not correctly reuse
460an existing structure. Therefore the following:
461
462 PEM_read_bio_X509(bp, &x, 0, NULL);
463
464where 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
469is guaranteed to work.
470
471=head1 RETURN CODES
472
473The read routines return either a pointer to the structure read or NULL
474if an error occurred.
475
476The write routines return 1 for success or 0 for failure.
477
478=head1 SEE ALSO
479
480L<EVP_get_cipherbyname(3)|EVP_get_cipherbyname>, L<EVP_BytesToKey(3)|EVP_BytesToKey(3)>
481