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