Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / lib / libcrypto / man / pem.3
CommitLineData
aac4ff6f 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
8b0cefbb
JR
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
aac4ff6f
PA
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<>.
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 62.\"
aac4ff6f
PA
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
8b0cefbb
JR
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"
aac4ff6f 132.TH pem 3 "2008-09-06" "0.9.8h" "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>
aac4ff6f
PA
139.Ve
140.PP
141.Vb 2
984263bc
MD
142\& EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
143\& pem_password_cb *cb, void *u);
aac4ff6f
PA
144.Ve
145.PP
146.Vb 2
984263bc
MD
147\& EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
148\& pem_password_cb *cb, void *u);
aac4ff6f
PA
149.Ve
150.PP
151.Vb 3
984263bc
MD
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);
aac4ff6f
PA
155.Ve
156.PP
157.Vb 3
984263bc
MD
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);
aac4ff6f
PA
161.Ve
162.PP
163.Vb 3
984263bc
MD
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);
aac4ff6f
PA
167.Ve
168.PP
169.Vb 3
984263bc
MD
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);
aac4ff6f
PA
173.Ve
174.PP
175.Vb 3
984263bc
MD
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);
aac4ff6f
PA
179.Ve
180.PP
181.Vb 3
984263bc
MD
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);
aac4ff6f
PA
185.Ve
186.PP
187.Vb 2
984263bc
MD
188\& EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
189\& pem_password_cb *cb, void *u);
aac4ff6f
PA
190.Ve
191.PP
192.Vb 2
984263bc
MD
193\& EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
194\& pem_password_cb *cb, void *u);
aac4ff6f
PA
195.Ve
196.PP
197.Vb 2
984263bc
MD
198\& int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
199\& int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
aac4ff6f
PA
200.Ve
201.PP
202.Vb 2
984263bc
MD
203\& RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
204\& pem_password_cb *cb, void *u);
aac4ff6f
PA
205.Ve
206.PP
207.Vb 2
984263bc
MD
208\& RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
209\& pem_password_cb *cb, void *u);
aac4ff6f
PA
210.Ve
211.PP
212.Vb 3
984263bc
MD
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);
aac4ff6f
PA
216.Ve
217.PP
218.Vb 3
984263bc
MD
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);
aac4ff6f
PA
222.Ve
223.PP
224.Vb 2
984263bc
MD
225\& RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
226\& pem_password_cb *cb, void *u);
aac4ff6f
PA
227.Ve
228.PP
229.Vb 2
984263bc
MD
230\& RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
231\& pem_password_cb *cb, void *u);
aac4ff6f
PA
232.Ve
233.PP
234.Vb 1
984263bc 235\& int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
aac4ff6f
PA
236.Ve
237.PP
238.Vb 1
984263bc 239\& int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
aac4ff6f
PA
240.Ve
241.PP
242.Vb 2
984263bc
MD
243\& RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
244\& pem_password_cb *cb, void *u);
aac4ff6f
PA
245.Ve
246.PP
247.Vb 2
984263bc
MD
248\& RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
249\& pem_password_cb *cb, void *u);
aac4ff6f
PA
250.Ve
251.PP
252.Vb 1
984263bc 253\& int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
aac4ff6f
PA
254.Ve
255.PP
256.Vb 1
984263bc 257\& int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
aac4ff6f
PA
258.Ve
259.PP
260.Vb 2
984263bc
MD
261\& DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
262\& pem_password_cb *cb, void *u);
aac4ff6f
PA
263.Ve
264.PP
265.Vb 2
984263bc
MD
266\& DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
267\& pem_password_cb *cb, void *u);
aac4ff6f
PA
268.Ve
269.PP
270.Vb 3
984263bc
MD
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);
aac4ff6f
PA
274.Ve
275.PP
276.Vb 3
984263bc
MD
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);
aac4ff6f
PA
280.Ve
281.PP
282.Vb 2
984263bc
MD
283\& DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
284\& pem_password_cb *cb, void *u);
aac4ff6f
PA
285.Ve
286.PP
287.Vb 2
984263bc
MD
288\& DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
289\& pem_password_cb *cb, void *u);
aac4ff6f
PA
290.Ve
291.PP
292.Vb 1
984263bc 293\& int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
aac4ff6f
PA
294.Ve
295.PP
296.Vb 1
984263bc 297\& int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
aac4ff6f
PA
298.Ve
299.PP
300.Vb 1
984263bc 301\& DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
aac4ff6f
PA
302.Ve
303.PP
304.Vb 1
984263bc 305\& DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
aac4ff6f
PA
306.Ve
307.PP
308.Vb 1
984263bc 309\& int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
aac4ff6f
PA
310.Ve
311.PP
312.Vb 1
984263bc 313\& int PEM_write_DSAparams(FILE *fp, DSA *x);
aac4ff6f
PA
314.Ve
315.PP
316.Vb 1
984263bc 317\& DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
aac4ff6f
PA
318.Ve
319.PP
320.Vb 1
984263bc 321\& DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
aac4ff6f
PA
322.Ve
323.PP
324.Vb 1
984263bc 325\& int PEM_write_bio_DHparams(BIO *bp, DH *x);
aac4ff6f
PA
326.Ve
327.PP
328.Vb 1
984263bc 329\& int PEM_write_DHparams(FILE *fp, DH *x);
aac4ff6f
PA
330.Ve
331.PP
332.Vb 1
984263bc 333\& X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
aac4ff6f
PA
334.Ve
335.PP
336.Vb 1
984263bc 337\& X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
aac4ff6f
PA
338.Ve
339.PP
340.Vb 1
984263bc 341\& int PEM_write_bio_X509(BIO *bp, X509 *x);
aac4ff6f
PA
342.Ve
343.PP
344.Vb 1
984263bc 345\& int PEM_write_X509(FILE *fp, X509 *x);
aac4ff6f
PA
346.Ve
347.PP
348.Vb 1
984263bc 349\& X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
aac4ff6f
PA
350.Ve
351.PP
352.Vb 1
984263bc 353\& X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
aac4ff6f
PA
354.Ve
355.PP
356.Vb 1
984263bc 357\& int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
aac4ff6f
PA
358.Ve
359.PP
360.Vb 1
984263bc 361\& int PEM_write_X509_AUX(FILE *fp, X509 *x);
aac4ff6f
PA
362.Ve
363.PP
364.Vb 2
984263bc
MD
365\& X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
366\& pem_password_cb *cb, void *u);
aac4ff6f
PA
367.Ve
368.PP
369.Vb 2
984263bc
MD
370\& X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
371\& pem_password_cb *cb, void *u);
aac4ff6f
PA
372.Ve
373.PP
374.Vb 1
984263bc 375\& int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
aac4ff6f
PA
376.Ve
377.PP
378.Vb 1
984263bc 379\& int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
aac4ff6f
PA
380.Ve
381.PP
382.Vb 1
984263bc 383\& int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
aac4ff6f
PA
384.Ve
385.PP
386.Vb 1
984263bc 387\& int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
aac4ff6f
PA
388.Ve
389.PP
390.Vb 6
984263bc
MD
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);
aac4ff6f
PA
397.Ve
398.PP
399.Vb 1
984263bc 400\& PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
aac4ff6f
PA
401.Ve
402.PP
403.Vb 1
984263bc 404\& PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
aac4ff6f
PA
405.Ve
406.PP
407.Vb 1
984263bc 408\& int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
aac4ff6f
PA
409.Ve
410.PP
411.Vb 1
984263bc 412\& int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
aac4ff6f
PA
413.Ve
414.PP
415.Vb 3
984263bc
MD
416\& NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,
417\& NETSCAPE_CERT_SEQUENCE **x,
418\& pem_password_cb *cb, void *u);
aac4ff6f
PA
419.Ve
420.PP
421.Vb 3
984263bc
MD
422\& NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,
423\& NETSCAPE_CERT_SEQUENCE **x,
424\& pem_password_cb *cb, void *u);
aac4ff6f
PA
425.Ve
426.PP
427.Vb 1
984263bc 428\& int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);
aac4ff6f
PA
429.Ve
430.PP
431.Vb 1
984263bc
MD
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
aac4ff6f 506an X509 structure.
984263bc
MD
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);
aac4ff6f
PA
671.Ve
672.PP
673.Vb 3
984263bc
MD
674\& /* get pass phrase, length 'len' into 'tmp' */
675\& tmp = "hello";
676\& len = strlen(tmp);
aac4ff6f
PA
677.Ve
678.PP
679.Vb 6
984263bc
MD
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
aac4ff6f 713The private key (or other data) takes the following form:
984263bc
MD
714.PP
715.Vb 3
aac4ff6f
PA
716\& -----BEGIN RSA PRIVATE KEY-----
717\& Proc-Type: 4,ENCRYPTED
718\& DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
719.Ve
720.PP
721.Vb 2
984263bc 722\& ...base64 encoded data...
aac4ff6f 723\& -----END RSA PRIVATE KEY-----
984263bc 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
aac4ff6f 744where \fBx\fR already contains a valid certificate, may not work, whereas:
984263bc
MD
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.