Regenerate the manual pages after the OpenSSL update to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / pem.3
CommitLineData
8b0cefbb
JR
1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
984263bc 32.tr \(*W-|\(bv\*(Tr
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
8b0cefbb
JR
59. nr % 0
60. rr F
984263bc 61.\}
8b0cefbb
JR
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
984263bc 66.if n .na
8b0cefbb
JR
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
8b0cefbb
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
8b0cefbb
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
8b0cefbb 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
8b0cefbb
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
8b0cefbb
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
8b0cefbb 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
8b0cefbb
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
8b0cefbb
JR
129.\" ========================================================================
130.\"
131.IX Title "pem 3"
132.TH pem 3 "2004-12-18" "0.9.7e" "OpenSSL"
984263bc 133.SH "NAME"
74dab6c2 134PEM \- PEM routines
984263bc 135.SH "SYNOPSIS"
8b0cefbb 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/pem.h>
139.Ve
8b0cefbb 140.PP
984263bc
MD
141.Vb 2
142\& EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
143\& pem_password_cb *cb, void *u);
144.Ve
8b0cefbb 145.PP
984263bc
MD
146.Vb 2
147\& EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
148\& pem_password_cb *cb, void *u);
149.Ve
8b0cefbb 150.PP
984263bc
MD
151.Vb 3
152\& int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
153\& unsigned char *kstr, int klen,
154\& pem_password_cb *cb, void *u);
155.Ve
8b0cefbb 156.PP
984263bc
MD
157.Vb 3
158\& int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
159\& unsigned char *kstr, int klen,
160\& pem_password_cb *cb, void *u);
161.Ve
8b0cefbb 162.PP
984263bc
MD
163.Vb 3
164\& int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
165\& char *kstr, int klen,
166\& pem_password_cb *cb, void *u);
167.Ve
8b0cefbb 168.PP
984263bc
MD
169.Vb 3
170\& int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
171\& char *kstr, int klen,
172\& pem_password_cb *cb, void *u);
173.Ve
8b0cefbb 174.PP
984263bc
MD
175.Vb 3
176\& int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
177\& char *kstr, int klen,
178\& pem_password_cb *cb, void *u);
179.Ve
8b0cefbb 180.PP
984263bc
MD
181.Vb 3
182\& int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
183\& char *kstr, int klen,
184\& pem_password_cb *cb, void *u);
185.Ve
8b0cefbb 186.PP
984263bc
MD
187.Vb 2
188\& EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
189\& pem_password_cb *cb, void *u);
190.Ve
8b0cefbb 191.PP
984263bc
MD
192.Vb 2
193\& EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
194\& pem_password_cb *cb, void *u);
195.Ve
8b0cefbb 196.PP
984263bc
MD
197.Vb 2
198\& int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
199\& int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
200.Ve
8b0cefbb 201.PP
984263bc
MD
202.Vb 2
203\& RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
204\& pem_password_cb *cb, void *u);
205.Ve
8b0cefbb 206.PP
984263bc
MD
207.Vb 2
208\& RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
209\& pem_password_cb *cb, void *u);
210.Ve
8b0cefbb 211.PP
984263bc
MD
212.Vb 3
213\& int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,
214\& unsigned char *kstr, int klen,
215\& pem_password_cb *cb, void *u);
216.Ve
8b0cefbb 217.PP
984263bc
MD
218.Vb 3
219\& int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,
220\& unsigned char *kstr, int klen,
221\& pem_password_cb *cb, void *u);
222.Ve
8b0cefbb 223.PP
984263bc
MD
224.Vb 2
225\& RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
226\& pem_password_cb *cb, void *u);
227.Ve
8b0cefbb 228.PP
984263bc
MD
229.Vb 2
230\& RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
231\& pem_password_cb *cb, void *u);
232.Ve
8b0cefbb 233.PP
984263bc
MD
234.Vb 1
235\& int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
236.Ve
8b0cefbb 237.PP
984263bc
MD
238.Vb 1
239\& int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
240.Ve
8b0cefbb 241.PP
984263bc
MD
242.Vb 2
243\& RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
244\& pem_password_cb *cb, void *u);
245.Ve
8b0cefbb 246.PP
984263bc
MD
247.Vb 2
248\& RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
249\& pem_password_cb *cb, void *u);
250.Ve
8b0cefbb 251.PP
984263bc
MD
252.Vb 1
253\& int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
254.Ve
8b0cefbb 255.PP
984263bc
MD
256.Vb 1
257\& int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
258.Ve
8b0cefbb 259.PP
984263bc
MD
260.Vb 2
261\& DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
262\& pem_password_cb *cb, void *u);
263.Ve
8b0cefbb 264.PP
984263bc
MD
265.Vb 2
266\& DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
267\& pem_password_cb *cb, void *u);
268.Ve
8b0cefbb 269.PP
984263bc
MD
270.Vb 3
271\& int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,
272\& unsigned char *kstr, int klen,
273\& pem_password_cb *cb, void *u);
274.Ve
8b0cefbb 275.PP
984263bc
MD
276.Vb 3
277\& int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,
278\& unsigned char *kstr, int klen,
279\& pem_password_cb *cb, void *u);
280.Ve
8b0cefbb 281.PP
984263bc
MD
282.Vb 2
283\& DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
284\& pem_password_cb *cb, void *u);
285.Ve
8b0cefbb 286.PP
984263bc
MD
287.Vb 2
288\& DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
289\& pem_password_cb *cb, void *u);
290.Ve
8b0cefbb 291.PP
984263bc
MD
292.Vb 1
293\& int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
294.Ve
8b0cefbb 295.PP
984263bc
MD
296.Vb 1
297\& int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
298.Ve
8b0cefbb 299.PP
984263bc
MD
300.Vb 1
301\& DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
302.Ve
8b0cefbb 303.PP
984263bc
MD
304.Vb 1
305\& DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
306.Ve
8b0cefbb 307.PP
984263bc
MD
308.Vb 1
309\& int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
310.Ve
8b0cefbb 311.PP
984263bc
MD
312.Vb 1
313\& int PEM_write_DSAparams(FILE *fp, DSA *x);
314.Ve
8b0cefbb 315.PP
984263bc
MD
316.Vb 1
317\& DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
318.Ve
8b0cefbb 319.PP
984263bc
MD
320.Vb 1
321\& DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
322.Ve
8b0cefbb 323.PP
984263bc
MD
324.Vb 1
325\& int PEM_write_bio_DHparams(BIO *bp, DH *x);
326.Ve
8b0cefbb 327.PP
984263bc
MD
328.Vb 1
329\& int PEM_write_DHparams(FILE *fp, DH *x);
330.Ve
8b0cefbb 331.PP
984263bc
MD
332.Vb 1
333\& X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
334.Ve
8b0cefbb 335.PP
984263bc
MD
336.Vb 1
337\& X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
338.Ve
8b0cefbb 339.PP
984263bc
MD
340.Vb 1
341\& int PEM_write_bio_X509(BIO *bp, X509 *x);
342.Ve
8b0cefbb 343.PP
984263bc
MD
344.Vb 1
345\& int PEM_write_X509(FILE *fp, X509 *x);
346.Ve
8b0cefbb 347.PP
984263bc
MD
348.Vb 1
349\& X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
350.Ve
8b0cefbb 351.PP
984263bc
MD
352.Vb 1
353\& X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
354.Ve
8b0cefbb 355.PP
984263bc
MD
356.Vb 1
357\& int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
358.Ve
8b0cefbb 359.PP
984263bc
MD
360.Vb 1
361\& int PEM_write_X509_AUX(FILE *fp, X509 *x);
362.Ve
8b0cefbb 363.PP
984263bc
MD
364.Vb 2
365\& X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
366\& pem_password_cb *cb, void *u);
367.Ve
8b0cefbb 368.PP
984263bc
MD
369.Vb 2
370\& X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
371\& pem_password_cb *cb, void *u);
372.Ve
8b0cefbb 373.PP
984263bc
MD
374.Vb 1
375\& int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
376.Ve
8b0cefbb 377.PP
984263bc
MD
378.Vb 1
379\& int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
380.Ve
8b0cefbb 381.PP
984263bc
MD
382.Vb 1
383\& int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
384.Ve
8b0cefbb 385.PP
984263bc
MD
386.Vb 1
387\& int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
388.Ve
8b0cefbb 389.PP
984263bc
MD
390.Vb 6
391\& X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,
392\& pem_password_cb *cb, void *u);
393\& X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
394\& pem_password_cb *cb, void *u);
395\& int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x);
396\& int PEM_write_X509_CRL(FILE *fp, X509_CRL *x);
397.Ve
8b0cefbb 398.PP
984263bc
MD
399.Vb 1
400\& PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
401.Ve
8b0cefbb 402.PP
984263bc
MD
403.Vb 1
404\& PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
405.Ve
8b0cefbb 406.PP
984263bc
MD
407.Vb 1
408\& int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
409.Ve
8b0cefbb 410.PP
984263bc
MD
411.Vb 1
412\& int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
413.Ve
8b0cefbb 414.PP
984263bc
MD
415.Vb 3
416\& NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,
417\& NETSCAPE_CERT_SEQUENCE **x,
418\& pem_password_cb *cb, void *u);
419.Ve
8b0cefbb 420.PP
984263bc
MD
421.Vb 3
422\& NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,
423\& NETSCAPE_CERT_SEQUENCE **x,
424\& pem_password_cb *cb, void *u);
425.Ve
8b0cefbb 426.PP
984263bc
MD
427.Vb 1
428\& int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);
429.Ve
8b0cefbb 430.PP
984263bc
MD
431.Vb 1
432\& int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x);
433.Ve
434.SH "DESCRIPTION"
8b0cefbb
JR
435.IX Header "DESCRIPTION"
436The \s-1PEM\s0 functions read or write structures in \s-1PEM\s0 format. In
437this sense \s-1PEM\s0 format is simply base64 encoded data surrounded
984263bc
MD
438by header lines.
439.PP
440For more details about the meaning of arguments see the
8b0cefbb 441\&\fB\s-1PEM\s0 \s-1FUNCTION\s0 \s-1ARGUMENTS\s0\fR section.
984263bc
MD
442.PP
443Each operation has four functions associated with it. For
8b0cefbb 444clarity the term "\fBfoobar\fR functions" will be used to collectively
984263bc 445refer to the \fIPEM_read_bio_foobar()\fR, \fIPEM_read_foobar()\fR,
8b0cefbb 446\&\fIPEM_write_bio_foobar()\fR and \fIPEM_write_foobar()\fR functions.
984263bc
MD
447.PP
448The \fBPrivateKey\fR functions read or write a private key in
8b0cefbb
JR
449\&\s-1PEM\s0 format using an \s-1EVP_PKEY\s0 structure. The write routines use
450\&\*(L"traditional\*(R" private key format and can handle both \s-1RSA\s0 and \s-1DSA\s0
984263bc
MD
451private keys. The read functions can additionally transparently
452handle PKCS#8 format encrypted and unencrypted keys too.
453.PP
8b0cefbb
JR
454\&\fIPEM_write_bio_PKCS8PrivateKey()\fR and \fIPEM_write_PKCS8PrivateKey()\fR
455write a private key in an \s-1EVP_PKEY\s0 structure in PKCS#8
984263bc
MD
456EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption
457algorithms. The \fBcipher\fR argument specifies the encryption algoritm to
8b0cefbb
JR
458use: unlike all other \s-1PEM\s0 routines the encryption is applied at the
459PKCS#8 level and not in the \s-1PEM\s0 headers. If \fBcipher\fR is \s-1NULL\s0 then no
984263bc
MD
460encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead.
461.PP
8b0cefbb 462\&\fIPEM_write_bio_PKCS8PrivateKey_nid()\fR and \fIPEM_write_PKCS8PrivateKey_nid()\fR
984263bc
MD
463also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
464it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
8b0cefbb
JR
465to use is specified in the \fBnid\fR parameter and should be the \s-1NID\s0 of the
466corresponding \s-1OBJECT\s0 \s-1IDENTIFIER\s0 (see \s-1NOTES\s0 section).
984263bc 467.PP
8b0cefbb 468The \fB\s-1PUBKEY\s0\fR functions process a public key using an \s-1EVP_PKEY\s0
984263bc
MD
469structure. The public key is encoded as a SubjectPublicKeyInfo
470structure.
471.PP
8b0cefbb
JR
472The \fBRSAPrivateKey\fR functions process an \s-1RSA\s0 private key using an
473\&\s-1RSA\s0 structure. It handles the same formats as the \fBPrivateKey\fR
474functions but an error occurs if the private key is not \s-1RSA\s0.
984263bc 475.PP
8b0cefbb
JR
476The \fBRSAPublicKey\fR functions process an \s-1RSA\s0 public key using an
477\&\s-1RSA\s0 structure. The public key is encoded using a PKCS#1 RSAPublicKey
984263bc
MD
478structure.
479.PP
8b0cefbb
JR
480The \fB\s-1RSA_PUBKEY\s0\fR functions also process an \s-1RSA\s0 public key using
481an \s-1RSA\s0 structure. However the public key is encoded using a
984263bc 482SubjectPublicKeyInfo structure and an error occurs if the public
8b0cefbb 483key is not \s-1RSA\s0.
984263bc 484.PP
8b0cefbb
JR
485The \fBDSAPrivateKey\fR functions process a \s-1DSA\s0 private key using a
486\&\s-1DSA\s0 structure. It handles the same formats as the \fBPrivateKey\fR
487functions but an error occurs if the private key is not \s-1DSA\s0.
984263bc 488.PP
8b0cefbb
JR
489The \fB\s-1DSA_PUBKEY\s0\fR functions process a \s-1DSA\s0 public key using
490a \s-1DSA\s0 structure. The public key is encoded using a
984263bc 491SubjectPublicKeyInfo structure and an error occurs if the public
8b0cefbb 492key is not \s-1DSA\s0.
984263bc 493.PP
8b0cefbb 494The \fBDSAparams\fR functions process \s-1DSA\s0 parameters using a \s-1DSA\s0
984263bc
MD
495structure. The parameters are encoded using a foobar structure.
496.PP
8b0cefbb 497The \fBDHparams\fR functions process \s-1DH\s0 parameters using a \s-1DH\s0
984263bc
MD
498structure. The parameters are encoded using a PKCS#3 DHparameter
499structure.
500.PP
501The \fBX509\fR functions process an X509 certificate using an X509
502structure. They will also process a trusted X509 certificate but
503any trust settings are discarded.
504.PP
505The \fBX509_AUX\fR functions process a trusted X509 certificate using
506an X509 structure.
507.PP
508The \fBX509_REQ\fR and \fBX509_REQ_NEW\fR functions process a PKCS#10
509certificate request using an X509_REQ structure. The \fBX509_REQ\fR
8b0cefbb
JR
510write functions use \fB\s-1CERTIFICATE\s0 \s-1REQUEST\s0\fR in the header whereas
511the \fBX509_REQ_NEW\fR functions use \fB\s-1NEW\s0 \s-1CERTIFICATE\s0 \s-1REQUEST\s0\fR
984263bc
MD
512(as required by some CAs). The \fBX509_REQ\fR read functions will
513handle either form so there are no \fBX509_REQ_NEW\fR read functions.
514.PP
8b0cefbb 515The \fBX509_CRL\fR functions process an X509 \s-1CRL\s0 using an X509_CRL
984263bc
MD
516structure.
517.PP
8b0cefbb 518The \fB\s-1PKCS7\s0\fR functions process a PKCS#7 ContentInfo using a \s-1PKCS7\s0
984263bc
MD
519structure.
520.PP
8b0cefbb
JR
521The \fB\s-1NETSCAPE_CERT_SEQUENCE\s0\fR functions process a Netscape Certificate
522Sequence using a \s-1NETSCAPE_CERT_SEQUENCE\s0 structure.
984263bc 523.SH "PEM FUNCTION ARGUMENTS"
8b0cefbb
JR
524.IX Header "PEM FUNCTION ARGUMENTS"
525The \s-1PEM\s0 functions have many common arguments.
984263bc 526.PP
8b0cefbb 527The \fBbp\fR \s-1BIO\s0 parameter (if present) specifies the \s-1BIO\s0 to read from
984263bc
MD
528or write to.
529.PP
8b0cefbb 530The \fBfp\fR \s-1FILE\s0 parameter (if present) specifies the \s-1FILE\s0 pointer to
984263bc
MD
531read from or write to.
532.PP
8b0cefbb
JR
533The \s-1PEM\s0 read functions all take an argument \fB\s-1TYPE\s0 **x\fR and return
534a \fB\s-1TYPE\s0 *\fR pointer. Where \fB\s-1TYPE\s0\fR is whatever structure the function
535uses. If \fBx\fR is \s-1NULL\s0 then the parameter is ignored. If \fBx\fR is not
536\&\s-1NULL\s0 but \fB*x\fR is \s-1NULL\s0 then the structure returned will be written
537to \fB*x\fR. If neither \fBx\fR nor \fB*x\fR is \s-1NULL\s0 then an attempt is made
538to reuse the structure at \fB*x\fR (but see \s-1BUGS\s0 and \s-1EXAMPLES\s0 sections).
984263bc 539Irrespective of the value of \fBx\fR a pointer to the structure is always
8b0cefbb 540returned (or \s-1NULL\s0 if an error occurred).
984263bc 541.PP
8b0cefbb 542The \s-1PEM\s0 functions which write private keys take an \fBenc\fR parameter
984263bc 543which specifies the encryption algorithm to use, encryption is done
8b0cefbb 544at the \s-1PEM\s0 level. If this parameter is set to \s-1NULL\s0 then the private
984263bc
MD
545key is written in unencrypted form.
546.PP
547The \fBcb\fR argument is the callback to use when querying for the pass
8b0cefbb 548phrase used for encrypted \s-1PEM\s0 structures (normally only private keys).
984263bc 549.PP
8b0cefbb
JR
550For the \s-1PEM\s0 write routines if the \fBkstr\fR parameter is not \s-1NULL\s0 then
551\&\fBklen\fR bytes at \fBkstr\fR are used as the passphrase and \fBcb\fR is
984263bc
MD
552ignored.
553.PP
8b0cefbb
JR
554If the \fBcb\fR parameters is set to \s-1NULL\s0 and the \fBu\fR parameter is not
555\&\s-1NULL\s0 then the \fBu\fR parameter is interpreted as a null terminated string
556to use as the passphrase. If both \fBcb\fR and \fBu\fR are \s-1NULL\s0 then the
984263bc
MD
557default callback routine is used which will typically prompt for the
558passphrase on the current terminal with echoing turned off.
559.PP
560The default passphrase callback is sometimes inappropriate (for example
8b0cefbb 561in a \s-1GUI\s0 application) so an alternative can be supplied. The callback
984263bc
MD
562routine has the following form:
563.PP
564.Vb 1
565\& int cb(char *buf, int size, int rwflag, void *u);
566.Ve
8b0cefbb
JR
567.PP
568\&\fBbuf\fR is the buffer to write the passphrase to. \fBsize\fR is the maximum
984263bc
MD
569length of the passphrase (i.e. the size of buf). \fBrwflag\fR is a flag
570which is set to 0 when reading and 1 when writing. A typical routine
571will ask the user to verify the passphrase (for example by prompting
572for it twice) if \fBrwflag\fR is 1. The \fBu\fR parameter has the same
8b0cefbb 573value as the \fBu\fR parameter passed to the \s-1PEM\s0 routine. It allows
984263bc 574arbitrary data to be passed to the callback by the application
8b0cefbb
JR
575(for example a window handle in a \s-1GUI\s0 application). The callback
576\&\fBmust\fR return the number of characters in the passphrase or 0 if
984263bc
MD
577an error occurred.
578.SH "EXAMPLES"
8b0cefbb
JR
579.IX Header "EXAMPLES"
580Although the \s-1PEM\s0 routines take several arguments in almost all applications
581most of them are set to 0 or \s-1NULL\s0.
984263bc 582.PP
8b0cefbb 583Read a certificate in \s-1PEM\s0 format from a \s-1BIO:\s0
984263bc
MD
584.PP
585.Vb 6
586\& X509 *x;
74dab6c2 587\& x = PEM_read_bio_X509(bp, NULL, 0, NULL);
984263bc
MD
588\& if (x == NULL)
589\& {
590\& /* Error */
591\& }
592.Ve
8b0cefbb 593.PP
984263bc
MD
594Alternative method:
595.PP
596.Vb 5
597\& X509 *x = NULL;
598\& if (!PEM_read_bio_X509(bp, &x, 0, NULL))
599\& {
600\& /* Error */
601\& }
602.Ve
8b0cefbb
JR
603.PP
604Write a certificate to a \s-1BIO:\s0
984263bc
MD
605.PP
606.Vb 4
607\& if (!PEM_write_bio_X509(bp, x))
608\& {
609\& /* Error */
610\& }
611.Ve
8b0cefbb
JR
612.PP
613Write an unencrypted private key to a \s-1FILE\s0 pointer:
984263bc
MD
614.PP
615.Vb 4
616\& if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL))
617\& {
618\& /* Error */
619\& }
620.Ve
8b0cefbb
JR
621.PP
622Write a private key (using traditional format) to a \s-1BIO\s0 using
623triple \s-1DES\s0 encryption, the pass phrase is prompted for:
984263bc
MD
624.PP
625.Vb 4
626\& if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
627\& {
628\& /* Error */
629\& }
630.Ve
8b0cefbb
JR
631.PP
632Write a private key (using PKCS#8 format) to a \s-1BIO\s0 using triple
633\&\s-1DES\s0 encryption, using the pass phrase \*(L"hello\*(R":
984263bc
MD
634.PP
635.Vb 4
636\& if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello"))
637\& {
638\& /* Error */
639\& }
640.Ve
8b0cefbb
JR
641.PP
642Read a private key from a \s-1BIO\s0 using the pass phrase \*(L"hello\*(R":
984263bc
MD
643.PP
644.Vb 5
645\& key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
646\& if (key == NULL)
647\& {
648\& /* Error */
649\& }
650.Ve
8b0cefbb
JR
651.PP
652Read a private key from a \s-1BIO\s0 using a pass phrase callback:
984263bc
MD
653.PP
654.Vb 5
655\& key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
656\& if (key == NULL)
657\& {
658\& /* Error */
659\& }
660.Ve
8b0cefbb 661.PP
984263bc
MD
662Skeleton pass phrase callback:
663.PP
664.Vb 6
665\& int pass_cb(char *buf, int size, int rwflag, void *u);
666\& {
667\& int len;
668\& char *tmp;
669\& /* We'd probably do something else if 'rwflag' is 1 */
670\& printf("Enter pass phrase for \e"%s\e"\en", u);
671.Ve
8b0cefbb 672.PP
984263bc
MD
673.Vb 3
674\& /* get pass phrase, length 'len' into 'tmp' */
675\& tmp = "hello";
676\& len = strlen(tmp);
677.Ve
8b0cefbb 678.PP
984263bc
MD
679.Vb 6
680\& if (len <= 0) return 0;
681\& /* if too long, truncate */
682\& if (len > size) len = size;
683\& memcpy(buf, tmp, len);
684\& return len;
685\& }
686.Ve
687.SH "NOTES"
8b0cefbb 688.IX Header "NOTES"
984263bc
MD
689The old \fBPrivateKey\fR write routines are retained for compatibility.
690New applications should write private keys using the
8b0cefbb 691\&\fIPEM_write_bio_PKCS8PrivateKey()\fR or \fIPEM_write_PKCS8PrivateKey()\fR routines
984263bc
MD
692because they are more secure (they use an iteration count of 2048 whereas
693the traditional routines use a count of 1) unless compatibility with older
694versions of OpenSSL is important.
695.PP
696The \fBPrivateKey\fR read routines can be used in all applications because
697they handle all formats transparently.
698.PP
8b0cefbb 699A frequent cause of problems is attempting to use the \s-1PEM\s0 routines like
984263bc
MD
700this:
701.PP
702.Vb 2
703\& X509 *x;
704\& PEM_read_bio_X509(bp, &x, 0, NULL);
705.Ve
8b0cefbb 706.PP
984263bc
MD
707this is a bug because an attempt will be made to reuse the data at \fBx\fR
708which is an uninitialised pointer.
709.SH "PEM ENCRYPTION FORMAT"
8b0cefbb 710.IX Header "PEM ENCRYPTION FORMAT"
984263bc
MD
711This old \fBPrivateKey\fR routines use a non standard technique for encryption.
712.PP
713The private key (or other data) takes the following form:
714.PP
715.Vb 3
716\& -----BEGIN RSA PRIVATE KEY-----
717\& Proc-Type: 4,ENCRYPTED
718\& DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
719.Ve
8b0cefbb 720.PP
984263bc
MD
721.Vb 2
722\& ...base64 encoded data...
723\& -----END RSA PRIVATE KEY-----
724.Ve
8b0cefbb
JR
725.PP
726The line beginning DEK-Info contains two comma separated pieces of information:
984263bc
MD
727the encryption algorithm name as used by \fIEVP_get_cipherbyname()\fR and an 8
728byte \fBsalt\fR encoded as a set of hexadecimal digits.
729.PP
730After this is the base64 encoded encrypted data.
731.PP
732The encryption key is determined using \fIEVP_bytestokey()\fR, using \fBsalt\fR and an
8b0cefbb 733iteration count of 1. The \s-1IV\s0 used is the value of \fBsalt\fR and *not* the \s-1IV\s0
984263bc
MD
734returned by \fIEVP_bytestokey()\fR.
735.SH "BUGS"
8b0cefbb
JR
736.IX Header "BUGS"
737The \s-1PEM\s0 read routines in some versions of OpenSSL will not correctly reuse
984263bc
MD
738an existing structure. Therefore the following:
739.PP
740.Vb 1
74dab6c2 741\& PEM_read_bio_X509(bp, &x, 0, NULL);
984263bc 742.Ve
8b0cefbb 743.PP
984263bc
MD
744where \fBx\fR already contains a valid certificate, may not work, whereas:
745.PP
746.Vb 2
747\& X509_free(x);
74dab6c2 748\& x = PEM_read_bio_X509(bp, NULL, 0, NULL);
984263bc 749.Ve
8b0cefbb 750.PP
984263bc
MD
751is guaranteed to work.
752.SH "RETURN CODES"
8b0cefbb
JR
753.IX Header "RETURN CODES"
754The read routines return either a pointer to the structure read or \s-1NULL\s0
755if an error occurred.
984263bc
MD
756.PP
757The write routines return 1 for success or 0 for failure.