Correct PPTP server firewall rules chain.
[tomato/davidwu.git] / release / src / router / openssl / doc / crypto / pem.pod
blob21e9fe3b98a908b37637be3a87fc9a4f380824d7
1 =pod
3 =head1 NAME
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
7 =head1 SYNOPSIS
9  #include <openssl/pem.h>
11  EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
12                                         pem_password_cb *cb, void *u);
14  EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
15                                         pem_password_cb *cb, void *u);
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);
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);
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);
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);
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);
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);
41  EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
42                                         pem_password_cb *cb, void *u);
44  EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
45                                         pem_password_cb *cb, void *u);
47  int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
48  int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
50  RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
51                                         pem_password_cb *cb, void *u);
53  RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
54                                         pem_password_cb *cb, void *u);
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);
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);
64  RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
65                                         pem_password_cb *cb, void *u);
67  RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
68                                         pem_password_cb *cb, void *u);
70  int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
72  int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
74  RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
75                                         pem_password_cb *cb, void *u);
77  RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
78                                         pem_password_cb *cb, void *u);
80  int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
82  int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
84  DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
85                                         pem_password_cb *cb, void *u);
87  DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
88                                         pem_password_cb *cb, void *u);
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);
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);
98  DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
99                                         pem_password_cb *cb, void *u);
101  DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
102                                         pem_password_cb *cb, void *u);
104  int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
106  int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
108  DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
110  DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
112  int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
114  int PEM_write_DSAparams(FILE *fp, DSA *x);
116  DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
118  DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
120  int PEM_write_bio_DHparams(BIO *bp, DH *x);
122  int PEM_write_DHparams(FILE *fp, DH *x);
124  X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
126  X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
128  int PEM_write_bio_X509(BIO *bp, X509 *x);
130  int PEM_write_X509(FILE *fp, X509 *x);
132  X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
134  X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
136  int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
138  int PEM_write_X509_AUX(FILE *fp, X509 *x);
140  X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
141                                         pem_password_cb *cb, void *u);
143  X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
144                                         pem_password_cb *cb, void *u);
146  int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
148  int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
150  int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
152  int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
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);
161  PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
163  PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
165  int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
167  int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
169  NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,
170                                                 NETSCAPE_CERT_SEQUENCE **x,
171                                                 pem_password_cb *cb, void *u);
173  NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,
174                                                 NETSCAPE_CERT_SEQUENCE **x,
175                                                 pem_password_cb *cb, void *u);
177  int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);
179  int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x);
181 =head1 DESCRIPTION
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.
187 For more details about the meaning of arguments see the
188 B<PEM FUNCTION ARGUMENTS> section.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
241 The B<DSAparams> functions process DSA parameters using a DSA
242 structure. The parameters are encoded using a foobar structure.
244 The B<DHparams> functions process DH parameters using a DH
245 structure. The parameters are encoded using a PKCS#3 DHparameter
246 structure.
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.
252 The B<X509_AUX> functions process a trusted X509 certificate using
253 an X509 structure. 
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.
262 The B<X509_CRL> functions process an X509 CRL using an X509_CRL
263 structure.
265 The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7
266 structure.
268 The B<NETSCAPE_CERT_SEQUENCE> functions process a Netscape Certificate
269 Sequence using a NETSCAPE_CERT_SEQUENCE structure.
271 =head1 PEM FUNCTION ARGUMENTS
273 The PEM functions have many common arguments.
275 The B<bp> BIO parameter (if present) specifies the BIO to read from
276 or write to.
278 The B<fp> FILE parameter (if present) specifies the FILE pointer to
279 read from or write to.
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).
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.
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).
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.
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.
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:
312  int cb(char *buf, int size, int rwflag, void *u);
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.
325 =head1 EXAMPLES
327 Although the PEM routines take several arguments in almost all applications
328 most of them are set to 0 or NULL.
330 Read a certificate in PEM format from a BIO:
332  X509 *x;
333  x = PEM_read_bio_X509(bp, NULL, 0, NULL);
334  if (x == NULL)
335         {
336         /* Error */
337         }
339 Alternative method:
341  X509 *x = NULL;
342  if (!PEM_read_bio_X509(bp, &x, 0, NULL))
343         {
344         /* Error */
345         }
347 Write a certificate to a BIO:
349  if (!PEM_write_bio_X509(bp, x))
350         {
351         /* Error */
352         }
354 Write an unencrypted private key to a FILE pointer:
356  if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL))
357         {
358         /* Error */
359         }
361 Write a private key (using traditional format) to a BIO using
362 triple DES encryption, the pass phrase is prompted for:
364  if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
365         {
366         /* Error */
367         }
369 Write a private key (using PKCS#8 format) to a BIO using triple
370 DES encryption, using the pass phrase "hello":
372  if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello"))
373         {
374         /* Error */
375         }
377 Read a private key from a BIO using the pass phrase "hello":
379  key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
380  if (key == NULL)
381         {
382         /* Error */
383         }
385 Read a private key from a BIO using a pass phrase callback:
387  key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
388  if (key == NULL)
389         {
390         /* Error */
391         }
393 Skeleton pass phrase callback:
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);
402         /* get pass phrase, length 'len' into 'tmp' */
403         tmp = "hello";
404         len = strlen(tmp);
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         }
413 =head1 NOTES
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.
422 The B<PrivateKey> read routines can be used in all applications because
423 they handle all formats transparently.
425 A frequent cause of problems is attempting to use the PEM routines like
426 this:
428  X509 *x;
429  PEM_read_bio_X509(bp, &x, 0, NULL);
431 this is a bug because an attempt will be made to reuse the data at B<x>
432 which is an uninitialised pointer.
434 =head1 PEM ENCRYPTION FORMAT
436 This old B<PrivateKey> routines use a non standard technique for encryption.
438 The private key (or other data) takes the following form: 
440  -----BEGIN RSA PRIVATE KEY-----
441  Proc-Type: 4,ENCRYPTED
442  DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
444  ...base64 encoded data...
445  -----END RSA PRIVATE KEY-----
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.
451 After this is the base64 encoded encrypted data.
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().
457 =head1 BUGS
459 The PEM read routines in some versions of OpenSSL will not correctly reuse
460 an existing structure. Therefore the following:
462  PEM_read_bio_X509(bp, &x, 0, NULL);
464 where B<x> already contains a valid certificate, may not work, whereas: 
466  X509_free(x);
467  x = PEM_read_bio_X509(bp, NULL, 0, NULL);
469 is guaranteed to work.
471 =head1 RETURN CODES
473 The read routines return either a pointer to the structure read or NULL
474 if an error occurred.
476 The write routines return 1 for success or 0 for failure.
478 =head1 SEE ALSO
480 L<EVP_get_cipherbyname(3)|EVP_get_cipherbyname>, L<EVP_BytesToKey(3)|EVP_BytesToKey(3)>