]>
Commit | Line | Data |
---|---|---|
a29d78e9 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
91da5e77 | 5 | pem_password_cb, |
9256e8a2 RL |
6 | PEM_read_bio_PrivateKey_ex, PEM_read_bio_PrivateKey, |
7 | PEM_read_PrivateKey_ex, PEM_read_PrivateKey, | |
8 | PEM_write_bio_PrivateKey_ex, PEM_write_bio_PrivateKey, | |
9 | PEM_write_bio_PrivateKey_traditional, | |
10 | PEM_write_PrivateKey_ex, PEM_write_PrivateKey, | |
05dba815 | 11 | PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, |
f097f81c | 12 | PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, |
9256e8a2 RL |
13 | PEM_read_bio_PUBKEY_ex, PEM_read_bio_PUBKEY, |
14 | PEM_read_PUBKEY_ex, PEM_read_PUBKEY, | |
15 | PEM_write_bio_PUBKEY_ex, PEM_write_bio_PUBKEY, | |
16 | PEM_write_PUBKEY_ex, PEM_write_PUBKEY, | |
f097f81c DSH |
17 | PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, |
18 | PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, | |
19 | PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, | |
20 | PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, | |
21 | PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, | |
22 | PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, | |
23 | PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, | |
6e5ccd58 RL |
24 | PEM_write_DSA_PUBKEY, PEM_read_bio_Parameters_ex, PEM_read_bio_Parameters, |
25 | PEM_write_bio_Parameters, PEM_read_bio_DSAparams, PEM_read_DSAparams, | |
f097f81c DSH |
26 | PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, |
27 | PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, | |
28 | PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, | |
29 | PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, | |
30 | PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, | |
31 | PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, | |
32 | PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, | |
33 | PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, | |
a0474357 | 34 | PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines |
a29d78e9 DSH |
35 | |
36 | =head1 SYNOPSIS | |
37 | ||
38 | #include <openssl/pem.h> | |
39 | ||
5bf6d418 | 40 | typedef int pem_password_cb(char *buf, int size, int rwflag, void *u); |
91da5e77 | 41 | |
9256e8a2 RL |
42 | EVP_PKEY *PEM_read_bio_PrivateKey_ex(BIO *bp, EVP_PKEY **x, |
43 | pem_password_cb *cb, void *u, | |
44 | OSSL_LIB_CTX *libctx, const char *propq); | |
a29d78e9 | 45 | EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, |
a0474357 | 46 | pem_password_cb *cb, void *u); |
137b274a | 47 | EVP_PKEY *PEM_read_PrivateKey_ex(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, |
b4250010 | 48 | void *u, OSSL_LIB_CTX *libctx, |
137b274a | 49 | const char *propq); |
a29d78e9 | 50 | EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, |
a0474357 | 51 | pem_password_cb *cb, void *u); |
9256e8a2 RL |
52 | int PEM_write_bio_PrivateKey_ex(BIO *bp, const EVP_PKEY *x, |
53 | const EVP_CIPHER *enc, | |
54 | unsigned char *kstr, int klen, | |
55 | pem_password_cb *cb, void *u, | |
56 | OSSL_LIB_CTX *libctx, const char *propq); | |
9fdcc21f | 57 | int PEM_write_bio_PrivateKey(BIO *bp, const EVP_PKEY *x, const EVP_CIPHER *enc, |
a0474357 RS |
58 | unsigned char *kstr, int klen, |
59 | pem_password_cb *cb, void *u); | |
05dba815 DSH |
60 | int PEM_write_bio_PrivateKey_traditional(BIO *bp, EVP_PKEY *x, |
61 | const EVP_CIPHER *enc, | |
62 | unsigned char *kstr, int klen, | |
63 | pem_password_cb *cb, void *u); | |
9256e8a2 RL |
64 | int PEM_write_PrivateKey_ex(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, |
65 | unsigned char *kstr, int klen, | |
66 | pem_password_cb *cb, void *u, | |
67 | OSSL_LIB_CTX *libctx, const char *propq); | |
a29d78e9 | 68 | int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, |
a0474357 RS |
69 | unsigned char *kstr, int klen, |
70 | pem_password_cb *cb, void *u); | |
a29d78e9 | 71 | int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, |
a0474357 RS |
72 | char *kstr, int klen, |
73 | pem_password_cb *cb, void *u); | |
a29d78e9 | 74 | int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, |
a0474357 RS |
75 | char *kstr, int klen, |
76 | pem_password_cb *cb, void *u); | |
9fdcc21f | 77 | int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, const EVP_PKEY *x, int nid, |
a0474357 RS |
78 | char *kstr, int klen, |
79 | pem_password_cb *cb, void *u); | |
9fdcc21f | 80 | int PEM_write_PKCS8PrivateKey_nid(FILE *fp, const EVP_PKEY *x, int nid, |
a0474357 RS |
81 | char *kstr, int klen, |
82 | pem_password_cb *cb, void *u); | |
a29d78e9 | 83 | |
6e5ccd58 RL |
84 | EVP_PKEY *PEM_read_bio_PUBKEY_ex(BIO *bp, EVP_PKEY **x, |
85 | pem_password_cb *cb, void *u, | |
b4250010 | 86 | OSSL_LIB_CTX *libctx, const char *propq); |
a29d78e9 | 87 | EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, |
a0474357 | 88 | pem_password_cb *cb, void *u); |
6e5ccd58 RL |
89 | EVP_PKEY *PEM_read_PUBKEY_ex(FILE *fp, EVP_PKEY **x, |
90 | pem_password_cb *cb, void *u, | |
b4250010 | 91 | OSSL_LIB_CTX *libctx, const char *propq); |
a29d78e9 | 92 | EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, |
a0474357 | 93 | pem_password_cb *cb, void *u); |
9256e8a2 RL |
94 | int PEM_write_bio_PUBKEY_ex(BIO *bp, EVP_PKEY *x, |
95 | OSSL_LIB_CTX *libctx, const char *propq); | |
a29d78e9 | 96 | int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x); |
9256e8a2 RL |
97 | int PEM_write_PUBKEY_ex(FILE *fp, EVP_PKEY *x, |
98 | OSSL_LIB_CTX *libctx, const char *propq); | |
a29d78e9 DSH |
99 | int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x); |
100 | ||
e52b4215 SL |
101 | EVP_PKEY *PEM_read_bio_Parameters_ex(BIO *bp, EVP_PKEY **x, |
102 | OSSL_LIB_CTX *libctx, const char *propq); | |
103 | EVP_PKEY *PEM_read_bio_Parameters(BIO *bp, EVP_PKEY **x); | |
104 | int PEM_write_bio_Parameters(BIO *bp, const EVP_PKEY *x); | |
105 | ||
106 | X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u); | |
107 | X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u); | |
108 | int PEM_write_bio_X509(BIO *bp, X509 *x); | |
109 | int PEM_write_X509(FILE *fp, X509 *x); | |
110 | ||
111 | X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u); | |
112 | X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u); | |
113 | int PEM_write_bio_X509_AUX(BIO *bp, X509 *x); | |
114 | int PEM_write_X509_AUX(FILE *fp, X509 *x); | |
115 | ||
116 | X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x, | |
117 | pem_password_cb *cb, void *u); | |
118 | X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, | |
119 | pem_password_cb *cb, void *u); | |
120 | int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x); | |
121 | int PEM_write_X509_REQ(FILE *fp, X509_REQ *x); | |
122 | int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x); | |
123 | int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x); | |
124 | ||
125 | X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x, | |
126 | pem_password_cb *cb, void *u); | |
127 | X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, | |
128 | pem_password_cb *cb, void *u); | |
129 | int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x); | |
130 | int PEM_write_X509_CRL(FILE *fp, X509_CRL *x); | |
131 | ||
132 | PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u); | |
133 | PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u); | |
134 | int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x); | |
135 | int PEM_write_PKCS7(FILE *fp, PKCS7 *x); | |
136 | ||
3dbf8243 MC |
137 | The following functions have been deprecated since OpenSSL 3.0, and can be |
138 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
139 | see L<openssl_user_macros(7)>: | |
e52b4215 | 140 | |
a29d78e9 | 141 | RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x, |
a0474357 | 142 | pem_password_cb *cb, void *u); |
a29d78e9 | 143 | RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, |
a0474357 | 144 | pem_password_cb *cb, void *u); |
a29d78e9 | 145 | int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc, |
a0474357 RS |
146 | unsigned char *kstr, int klen, |
147 | pem_password_cb *cb, void *u); | |
a29d78e9 | 148 | int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, |
a0474357 RS |
149 | unsigned char *kstr, int klen, |
150 | pem_password_cb *cb, void *u); | |
a29d78e9 DSH |
151 | |
152 | RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x, | |
a0474357 | 153 | pem_password_cb *cb, void *u); |
a29d78e9 | 154 | RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, |
a0474357 | 155 | pem_password_cb *cb, void *u); |
a29d78e9 | 156 | int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x); |
a29d78e9 DSH |
157 | int PEM_write_RSAPublicKey(FILE *fp, RSA *x); |
158 | ||
159 | RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x, | |
a0474357 | 160 | pem_password_cb *cb, void *u); |
a29d78e9 | 161 | RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, |
a0474357 | 162 | pem_password_cb *cb, void *u); |
a29d78e9 | 163 | int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x); |
a29d78e9 DSH |
164 | int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x); |
165 | ||
166 | DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x, | |
a0474357 | 167 | pem_password_cb *cb, void *u); |
a29d78e9 | 168 | DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, |
a0474357 | 169 | pem_password_cb *cb, void *u); |
a29d78e9 | 170 | int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc, |
a0474357 RS |
171 | unsigned char *kstr, int klen, |
172 | pem_password_cb *cb, void *u); | |
a29d78e9 | 173 | int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, |
a0474357 RS |
174 | unsigned char *kstr, int klen, |
175 | pem_password_cb *cb, void *u); | |
a29d78e9 DSH |
176 | |
177 | DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x, | |
a0474357 | 178 | pem_password_cb *cb, void *u); |
a29d78e9 | 179 | DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, |
a0474357 | 180 | pem_password_cb *cb, void *u); |
a29d78e9 | 181 | int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x); |
a29d78e9 | 182 | int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x); |
a29d78e9 | 183 | DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u); |
a29d78e9 | 184 | DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u); |
a29d78e9 | 185 | int PEM_write_bio_DSAparams(BIO *bp, DSA *x); |
a29d78e9 DSH |
186 | int PEM_write_DSAparams(FILE *fp, DSA *x); |
187 | ||
188 | DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u); | |
a29d78e9 | 189 | DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u); |
a29d78e9 | 190 | int PEM_write_bio_DHparams(BIO *bp, DH *x); |
a29d78e9 DSH |
191 | int PEM_write_DHparams(FILE *fp, DH *x); |
192 | ||
a29d78e9 DSH |
193 | =head1 DESCRIPTION |
194 | ||
e52b4215 | 195 | All of the functions described on this page that have a I<TYPE> of B<DH>, B<DSA> |
7510aee2 E |
196 | and B<RSA> are deprecated. Applications should use L<OSSL_ENCODER_to_bio(3)> and |
197 | L<OSSL_DECODER_from_bio(3)> instead. | |
e52b4215 | 198 | |
a29d78e9 DSH |
199 | The PEM functions read or write structures in PEM format. In |
200 | this sense PEM format is simply base64 encoded data surrounded | |
201 | by header lines. | |
202 | ||
203 | For more details about the meaning of arguments see the | |
204 | B<PEM FUNCTION ARGUMENTS> section. | |
205 | ||
206 | Each operation has four functions associated with it. For | |
bbecf04e RL |
207 | brevity the term "B<I<TYPE>> functions" will be used below to collectively |
208 | refer to the B<PEM_read_bio_I<TYPE>>(), B<PEM_read_I<TYPE>>(), | |
209 | B<PEM_write_bio_I<TYPE>>(), and B<PEM_write_I<TYPE>>() functions. | |
a29d78e9 | 210 | |
137b274a | 211 | Some operations have additional variants that take a library context I<libctx> |
e48fe798 MC |
212 | and a property query string I<propq>. The B<X509>, B<X509_REQ> and B<X509_CRL> |
213 | objects may have an associated library context or property query string but | |
214 | there are no variants of these functions that take a library context or property | |
215 | query string parameter. In this case it is possible to set the appropriate | |
216 | library context or property query string by creating an empty B<X509>, | |
217 | B<X509_REQ> or B<X509_CRL> object using L<X509_new_ex(3)>, L<X509_REQ_new_ex(3)> | |
218 | or L<X509_CRL_new_ex(3)> respectively. Then pass the empty object as a parameter | |
219 | to the relevant PEM function. See the L</EXAMPLES> section below. | |
137b274a | 220 | |
9256e8a2 RL |
221 | The B<PrivateKey> functions read or write a private key in PEM format using |
222 | an EVP_PKEY structure. The write routines use PKCS#8 private key format and are | |
223 | equivalent to PEM_write_bio_PKCS8PrivateKey(). The read functions transparently | |
05dba815 | 224 | handle traditional and PKCS#8 format encrypted and unencrypted keys. |
a29d78e9 | 225 | |
a95d7574 RS |
226 | PEM_write_bio_PrivateKey_traditional() writes out a private key in the |
227 | "traditional" format with a simple private key marker and should only | |
228 | be used for compatibility with legacy programs. | |
05dba815 DSH |
229 | |
230 | PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private | |
231 | key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using | |
bbecf04e | 232 | PKCS#5 v2.0 password based encryption algorithms. The I<cipher> argument |
05dba815 DSH |
233 | specifies the encryption algorithm to use: unlike some other PEM routines the |
234 | encryption is applied at the PKCS#8 level and not in the PEM headers. If | |
bbecf04e | 235 | I<cipher> is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo |
05dba815 | 236 | structure is used instead. |
a29d78e9 DSH |
237 | |
238 | PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid() | |
239 | also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however | |
240 | it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm | |
bbecf04e | 241 | to use is specified in the I<nid> parameter and should be the NID of the |
a29d78e9 DSH |
242 | corresponding OBJECT IDENTIFIER (see NOTES section). |
243 | ||
244 | The B<PUBKEY> functions process a public key using an EVP_PKEY | |
245 | structure. The public key is encoded as a SubjectPublicKeyInfo | |
246 | structure. | |
247 | ||
248 | The B<RSAPrivateKey> functions process an RSA private key using an | |
05dba815 DSH |
249 | RSA structure. The write routines uses traditional format. The read |
250 | routines handles the same formats as the B<PrivateKey> | |
a29d78e9 DSH |
251 | functions but an error occurs if the private key is not RSA. |
252 | ||
253 | The B<RSAPublicKey> functions process an RSA public key using an | |
254 | RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey | |
255 | structure. | |
256 | ||
257 | The B<RSA_PUBKEY> functions also process an RSA public key using | |
8c1cbc72 | 258 | an RSA structure. However, the public key is encoded using a |
a29d78e9 DSH |
259 | SubjectPublicKeyInfo structure and an error occurs if the public |
260 | key is not RSA. | |
261 | ||
262 | The B<DSAPrivateKey> functions process a DSA private key using a | |
05dba815 DSH |
263 | DSA structure. The write routines uses traditional format. The read |
264 | routines handles the same formats as the B<PrivateKey> | |
a29d78e9 DSH |
265 | functions but an error occurs if the private key is not DSA. |
266 | ||
267 | The B<DSA_PUBKEY> functions process a DSA public key using | |
268 | a DSA structure. The public key is encoded using a | |
269 | SubjectPublicKeyInfo structure and an error occurs if the public | |
270 | key is not DSA. | |
271 | ||
9a6abb95 RL |
272 | The B<Parameters> functions read or write key parameters in PEM format using |
273 | an EVP_PKEY structure. The encoding depends on the type of key; for DSA key | |
274 | parameters, it will be a Dss-Parms structure as defined in RFC2459, and for DH | |
275 | key parameters, it will be a PKCS#3 DHparameter structure. I<These functions | |
276 | only exist for the B<BIO> type>. | |
277 | ||
a29d78e9 | 278 | The B<DSAparams> functions process DSA parameters using a DSA |
f097f81c DSH |
279 | structure. The parameters are encoded using a Dss-Parms structure |
280 | as defined in RFC2459. | |
a29d78e9 DSH |
281 | |
282 | The B<DHparams> functions process DH parameters using a DH | |
283 | structure. The parameters are encoded using a PKCS#3 DHparameter | |
284 | structure. | |
285 | ||
286 | The B<X509> functions process an X509 certificate using an X509 | |
287 | structure. They will also process a trusted X509 certificate but | |
288 | any trust settings are discarded. | |
289 | ||
290 | The B<X509_AUX> functions process a trusted X509 certificate using | |
1bc74519 | 291 | an X509 structure. |
a29d78e9 DSH |
292 | |
293 | The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10 | |
294 | certificate request using an X509_REQ structure. The B<X509_REQ> | |
295 | write functions use B<CERTIFICATE REQUEST> in the header whereas | |
296 | the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST> | |
297 | (as required by some CAs). The B<X509_REQ> read functions will | |
298 | handle either form so there are no B<X509_REQ_NEW> read functions. | |
299 | ||
300 | The B<X509_CRL> functions process an X509 CRL using an X509_CRL | |
301 | structure. | |
302 | ||
303 | The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7 | |
304 | structure. | |
305 | ||
a29d78e9 DSH |
306 | =head1 PEM FUNCTION ARGUMENTS |
307 | ||
308 | The PEM functions have many common arguments. | |
309 | ||
bbecf04e | 310 | The I<bp> BIO parameter (if present) specifies the BIO to read from |
a29d78e9 DSH |
311 | or write to. |
312 | ||
bbecf04e | 313 | The I<fp> FILE parameter (if present) specifies the FILE pointer to |
a29d78e9 DSH |
314 | read from or write to. |
315 | ||
bbecf04e RL |
316 | The PEM read functions all take an argument I<B<TYPE> **x> and return |
317 | a I<B<TYPE> *> pointer. Where I<B<TYPE>> is whatever structure the function | |
318 | uses. If I<x> is NULL then the parameter is ignored. If I<x> is not | |
319 | NULL but I<*x> is NULL then the structure returned will be written | |
320 | to I<*x>. If neither I<x> nor I<*x> is NULL then an attempt is made | |
321 | to reuse the structure at I<*x> (but see BUGS and EXAMPLES sections). | |
322 | Irrespective of the value of I<x> a pointer to the structure is always | |
a29d78e9 DSH |
323 | returned (or NULL if an error occurred). |
324 | ||
bbecf04e | 325 | The PEM functions which write private keys take an I<enc> parameter |
a29d78e9 DSH |
326 | which specifies the encryption algorithm to use, encryption is done |
327 | at the PEM level. If this parameter is set to NULL then the private | |
328 | key is written in unencrypted form. | |
329 | ||
bbecf04e | 330 | The I<cb> argument is the callback to use when querying for the pass |
a29d78e9 DSH |
331 | phrase used for encrypted PEM structures (normally only private keys). |
332 | ||
bbecf04e RL |
333 | For the PEM write routines if the I<kstr> parameter is not NULL then |
334 | I<klen> bytes at I<kstr> are used as the passphrase and I<cb> is | |
a29d78e9 DSH |
335 | ignored. |
336 | ||
bbecf04e | 337 | If the I<cb> parameters is set to NULL and the I<u> parameter is not |
5b5342e0 | 338 | NULL then the I<u> parameter is interpreted as a NUL terminated string |
bbecf04e | 339 | to use as the passphrase. If both I<cb> and I<u> are NULL then the |
a29d78e9 DSH |
340 | default callback routine is used which will typically prompt for the |
341 | passphrase on the current terminal with echoing turned off. | |
342 | ||
343 | The default passphrase callback is sometimes inappropriate (for example | |
344 | in a GUI application) so an alternative can be supplied. The callback | |
345 | routine has the following form: | |
346 | ||
347 | int cb(char *buf, int size, int rwflag, void *u); | |
348 | ||
bbecf04e RL |
349 | I<buf> is the buffer to write the passphrase to. I<size> is the maximum |
350 | length of the passphrase (i.e. the size of buf). I<rwflag> is a flag | |
a29d78e9 DSH |
351 | which is set to 0 when reading and 1 when writing. A typical routine |
352 | will ask the user to verify the passphrase (for example by prompting | |
bbecf04e RL |
353 | for it twice) if I<rwflag> is 1. The I<u> parameter has the same |
354 | value as the I<u> parameter passed to the PEM routine. It allows | |
a29d78e9 DSH |
355 | arbitrary data to be passed to the callback by the application |
356 | (for example a window handle in a GUI application). The callback | |
bbecf04e | 357 | I<must> return the number of characters in the passphrase or -1 if |
5b5342e0 TM |
358 | an error occurred. The passphrase can be arbitrary data; in the case where it |
359 | is a string, it is not NUL terminated. See the L</EXAMPLES> section below. | |
a29d78e9 | 360 | |
137b274a MC |
361 | Some implementations may need to use cryptographic algorithms during their |
362 | operation. If this is the case and I<libctx> and I<propq> parameters have been | |
363 | passed then any algorithm fetches will use that library context and property | |
364 | query string. Otherwise the default library context and property query string | |
365 | will be used. | |
366 | ||
a29d78e9 DSH |
367 | =head1 NOTES |
368 | ||
5cffc49f TM |
369 | The PEM reading functions will skip any extraneous content or PEM data of |
370 | a different type than they expect. This allows for example having a certificate | |
371 | (or multiple certificates) and a key in the PEM format in a single file. | |
372 | ||
a29d78e9 DSH |
373 | The old B<PrivateKey> write routines are retained for compatibility. |
374 | New applications should write private keys using the | |
375 | PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines | |
376 | because they are more secure (they use an iteration count of 2048 whereas | |
377 | the traditional routines use a count of 1) unless compatibility with older | |
378 | versions of OpenSSL is important. | |
379 | ||
380 | The B<PrivateKey> read routines can be used in all applications because | |
381 | they handle all formats transparently. | |
382 | ||
383 | A frequent cause of problems is attempting to use the PEM routines like | |
384 | this: | |
385 | ||
386 | X509 *x; | |
e9b77246 | 387 | |
a29d78e9 DSH |
388 | PEM_read_bio_X509(bp, &x, 0, NULL); |
389 | ||
bbecf04e | 390 | this is a bug because an attempt will be made to reuse the data at I<x> |
a29d78e9 DSH |
391 | which is an uninitialised pointer. |
392 | ||
84814344 RL |
393 | These functions make no assumption regarding the pass phrase received from the |
394 | password callback. | |
395 | It will simply be treated as a byte sequence. | |
396 | ||
06623ff0 DSH |
397 | =head1 PEM ENCRYPTION FORMAT |
398 | ||
a0474357 | 399 | These old B<PrivateKey> routines use a non standard technique for encryption. |
06623ff0 | 400 | |
1bc74519 | 401 | The private key (or other data) takes the following form: |
06623ff0 DSH |
402 | |
403 | -----BEGIN RSA PRIVATE KEY----- | |
404 | Proc-Type: 4,ENCRYPTED | |
405 | DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 | |
406 | ||
407 | ...base64 encoded data... | |
408 | -----END RSA PRIVATE KEY----- | |
409 | ||
a0474357 RS |
410 | The line beginning with I<Proc-Type> contains the version and the |
411 | protection on the encapsulated data. The line beginning I<DEK-Info> | |
412 | contains two comma separated values: the encryption algorithm name as | |
413 | used by EVP_get_cipherbyname() and an initialization vector used by the | |
414 | cipher encoded as a set of hexadecimal digits. After those two lines is | |
415 | the base64-encoded encrypted data. | |
06623ff0 | 416 | |
a0474357 | 417 | The encryption key is derived using EVP_BytesToKey(). The cipher's |
bbecf04e | 418 | initialization vector is passed to EVP_BytesToKey() as the I<salt> |
a0474357 RS |
419 | parameter. Internally, B<PKCS5_SALT_LEN> bytes of the salt are used |
420 | (regardless of the size of the initialization vector). The user's | |
bbecf04e | 421 | password is passed to EVP_BytesToKey() using the I<data> and I<datal> |
a0474357 RS |
422 | parameters. Finally, the library uses an iteration count of 1 for |
423 | EVP_BytesToKey(). | |
06623ff0 | 424 | |
bbecf04e RL |
425 | The I<key> derived by EVP_BytesToKey() along with the original initialization |
426 | vector is then used to decrypt the encrypted data. The I<iv> produced by | |
a0474357 RS |
427 | EVP_BytesToKey() is not utilized or needed, and NULL should be passed to |
428 | the function. | |
429 | ||
430 | The pseudo code to derive the key would look similar to: | |
431 | ||
432 | EVP_CIPHER* cipher = EVP_des_ede3_cbc(); | |
433 | EVP_MD* md = EVP_md5(); | |
434 | ||
ed576acd TM |
435 | unsigned int nkey = EVP_CIPHER_get_key_length(cipher); |
436 | unsigned int niv = EVP_CIPHER_get_iv_length(cipher); | |
a0474357 RS |
437 | unsigned char key[nkey]; |
438 | unsigned char iv[niv]; | |
439 | ||
440 | memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv); | |
441 | rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/); | |
2947af32 | 442 | if (rc != nkey) |
a0474357 | 443 | /* Error */ |
a0474357 RS |
444 | |
445 | /* On success, use key and iv to initialize the cipher */ | |
06623ff0 | 446 | |
a29d78e9 DSH |
447 | =head1 BUGS |
448 | ||
449 | The PEM read routines in some versions of OpenSSL will not correctly reuse | |
8c1cbc72 | 450 | an existing structure. Therefore, the following: |
a29d78e9 | 451 | |
e88c5777 | 452 | PEM_read_bio_X509(bp, &x, 0, NULL); |
a29d78e9 | 453 | |
bbecf04e | 454 | where I<x> already contains a valid certificate, may not work, whereas: |
a29d78e9 DSH |
455 | |
456 | X509_free(x); | |
e88c5777 | 457 | x = PEM_read_bio_X509(bp, NULL, 0, NULL); |
a29d78e9 | 458 | |
e48fe798 MC |
459 | is guaranteed to work. It is always acceptable for I<x> to contain a newly |
460 | allocated, empty B<X509> object (for example allocated via L<X509_new_ex(3)>). | |
a29d78e9 | 461 | |
1f13ad31 | 462 | =head1 RETURN VALUES |
a29d78e9 DSH |
463 | |
464 | The read routines return either a pointer to the structure read or NULL | |
9449e385 | 465 | if an error occurred. |
a29d78e9 DSH |
466 | |
467 | The write routines return 1 for success or 0 for failure. | |
d48e78f0 | 468 | |
4564e77a PY |
469 | =head1 EXAMPLES |
470 | ||
471 | Although the PEM routines take several arguments in almost all applications | |
472 | most of them are set to 0 or NULL. | |
473 | ||
6725682d SL |
474 | To read a certificate with a library context in PEM format from a BIO: |
475 | ||
d8652be0 | 476 | X509 *x = X509_new_ex(libctx, NULL); |
6725682d SL |
477 | |
478 | if (x == NULL) | |
479 | /* Error */ | |
480 | ||
481 | if (PEM_read_bio_X509(bp, &x, 0, NULL) == NULL) | |
482 | /* Error */ | |
483 | ||
4564e77a PY |
484 | Read a certificate in PEM format from a BIO: |
485 | ||
486 | X509 *x; | |
487 | ||
488 | x = PEM_read_bio_X509(bp, NULL, 0, NULL); | |
489 | if (x == NULL) | |
490 | /* Error */ | |
491 | ||
492 | Alternative method: | |
493 | ||
494 | X509 *x = NULL; | |
495 | ||
496 | if (!PEM_read_bio_X509(bp, &x, 0, NULL)) | |
497 | /* Error */ | |
498 | ||
499 | Write a certificate to a BIO: | |
500 | ||
501 | if (!PEM_write_bio_X509(bp, x)) | |
502 | /* Error */ | |
503 | ||
504 | Write a private key (using traditional format) to a BIO using | |
505 | triple DES encryption, the pass phrase is prompted for: | |
506 | ||
507 | if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) | |
508 | /* Error */ | |
509 | ||
510 | Write a private key (using PKCS#8 format) to a BIO using triple | |
511 | DES encryption, using the pass phrase "hello": | |
512 | ||
513 | if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), | |
514 | NULL, 0, 0, "hello")) | |
515 | /* Error */ | |
516 | ||
517 | Read a private key from a BIO using a pass phrase callback: | |
518 | ||
519 | key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); | |
520 | if (key == NULL) | |
521 | /* Error */ | |
522 | ||
523 | Skeleton pass phrase callback: | |
524 | ||
525 | int pass_cb(char *buf, int size, int rwflag, void *u) | |
526 | { | |
527 | ||
528 | /* We'd probably do something else if 'rwflag' is 1 */ | |
529 | printf("Enter pass phrase for \"%s\"\n", (char *)u); | |
530 | ||
531 | /* get pass phrase, length 'len' into 'tmp' */ | |
532 | char *tmp = "hello"; | |
533 | if (tmp == NULL) /* An error occurred */ | |
534 | return -1; | |
535 | ||
536 | size_t len = strlen(tmp); | |
537 | ||
538 | if (len > size) | |
539 | len = size; | |
540 | memcpy(buf, tmp, len); | |
541 | return len; | |
542 | } | |
543 | ||
b5c4bbbe JL |
544 | =head1 SEE ALSO |
545 | ||
546 | L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)>, | |
547 | L<passphrase-encoding(7)> | |
548 | ||
a0474357 RS |
549 | =head1 HISTORY |
550 | ||
551 | The old Netscape certificate sequences were no longer documented | |
a95d7574 | 552 | in OpenSSL 1.1.0; applications should use the PKCS7 standard instead |
a0474357 RS |
553 | as they will be formally deprecated in a future releases. |
554 | ||
6e5ccd58 RL |
555 | PEM_read_bio_PrivateKey_ex(), PEM_read_PrivateKey_ex(), |
556 | PEM_read_bio_PUBKEY_ex(), PEM_read_PUBKEY_ex() and | |
557 | PEM_read_bio_Parameters_ex() were introduced in OpenSSL 3.0. | |
137b274a | 558 | |
e52b4215 SL |
559 | The functions PEM_read_bio_RSAPrivateKey(), PEM_read_RSAPrivateKey(), |
560 | PEM_write_bio_RSAPrivateKey(), PEM_write_RSAPrivateKey(), | |
561 | PEM_read_bio_RSAPublicKey(), PEM_read_RSAPublicKey(), | |
562 | PEM_write_bio_RSAPublicKey(), PEM_write_RSAPublicKey(), | |
563 | PEM_read_bio_RSA_PUBKEY(), PEM_read_RSA_PUBKEY(), | |
564 | PEM_write_bio_RSA_PUBKEY(), PEM_write_RSA_PUBKEY(), | |
565 | PEM_read_bio_DSAPrivateKey(), PEM_read_DSAPrivateKey(), | |
566 | PEM_write_bio_DSAPrivateKey(), PEM_write_DSAPrivateKey(), | |
567 | PEM_read_bio_DSA_PUBKEY(), PEM_read_DSA_PUBKEY(), | |
568 | PEM_write_bio_DSA_PUBKEY(), PEM_write_DSA_PUBKEY(); | |
569 | PEM_read_bio_DSAparams(), PEM_read_DSAparams(), | |
570 | PEM_write_bio_DSAparams(), PEM_write_DSAparams(), | |
571 | PEM_read_bio_DHparams(), PEM_read_DHparams(), | |
572 | PEM_write_bio_DHparams() and PEM_write_DHparams() were deprecated in 3.0. | |
573 | ||
574 | ||
e2f92610 RS |
575 | =head1 COPYRIGHT |
576 | ||
fecb3aae | 577 | Copyright 2001-2022 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 578 | |
4746f25a | 579 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
580 | this file except in compliance with the License. You can obtain a copy |
581 | in the file LICENSE in the source distribution or at | |
582 | L<https://www.openssl.org/source/license.html>. | |
583 | ||
584 | =cut |