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