5 PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey,
6 PEM_write_bio_PrivateKey_traditional, PEM_write_PrivateKey,
7 PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey,
8 PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid,
9 PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY,
10 PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey,
11 PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey,
12 PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey,
13 PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY,
14 PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey,
15 PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey,
16 PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY,
17 PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams,
18 PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams,
19 PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams,
20 PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509,
21 PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX,
22 PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ,
23 PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW,
24 PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL,
25 PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7,
26 PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines
30 #include <openssl/pem.h>
32 EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
33 pem_password_cb *cb, void *u);
34 EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
35 pem_password_cb *cb, void *u);
36 int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
37 unsigned char *kstr, int klen,
38 pem_password_cb *cb, void *u);
39 int PEM_write_bio_PrivateKey_traditional(BIO *bp, EVP_PKEY *x,
40 const EVP_CIPHER *enc,
41 unsigned char *kstr, int klen,
42 pem_password_cb *cb, void *u);
43 int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
44 unsigned char *kstr, int klen,
45 pem_password_cb *cb, void *u);
47 int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
49 pem_password_cb *cb, void *u);
50 int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
52 pem_password_cb *cb, void *u);
53 int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
55 pem_password_cb *cb, void *u);
56 int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
58 pem_password_cb *cb, void *u);
60 EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
61 pem_password_cb *cb, void *u);
62 EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
63 pem_password_cb *cb, void *u);
64 int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
65 int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
67 RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
68 pem_password_cb *cb, void *u);
69 RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
70 pem_password_cb *cb, void *u);
71 int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,
72 unsigned char *kstr, int klen,
73 pem_password_cb *cb, void *u);
74 int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,
75 unsigned char *kstr, int klen,
76 pem_password_cb *cb, void *u);
78 RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
79 pem_password_cb *cb, void *u);
80 RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
81 pem_password_cb *cb, void *u);
82 int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
83 int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
85 RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
86 pem_password_cb *cb, void *u);
87 RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
88 pem_password_cb *cb, void *u);
89 int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
90 int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
92 DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
93 pem_password_cb *cb, void *u);
94 DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
95 pem_password_cb *cb, void *u);
96 int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,
97 unsigned char *kstr, int klen,
98 pem_password_cb *cb, void *u);
99 int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,
100 unsigned char *kstr, int klen,
101 pem_password_cb *cb, void *u);
103 DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
104 pem_password_cb *cb, void *u);
105 DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
106 pem_password_cb *cb, void *u);
107 int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
108 int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
110 DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
111 DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
112 int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
113 int PEM_write_DSAparams(FILE *fp, DSA *x);
115 DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
116 DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
117 int PEM_write_bio_DHparams(BIO *bp, DH *x);
118 int PEM_write_DHparams(FILE *fp, DH *x);
120 X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
121 X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
122 int PEM_write_bio_X509(BIO *bp, X509 *x);
123 int PEM_write_X509(FILE *fp, X509 *x);
125 X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
126 X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
127 int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
128 int PEM_write_X509_AUX(FILE *fp, X509 *x);
130 X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
131 pem_password_cb *cb, void *u);
132 X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
133 pem_password_cb *cb, void *u);
134 int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
135 int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
136 int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
137 int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
139 X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,
140 pem_password_cb *cb, void *u);
141 X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
142 pem_password_cb *cb, void *u);
143 int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x);
144 int PEM_write_X509_CRL(FILE *fp, X509_CRL *x);
146 PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
147 PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
148 int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
149 int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
153 The PEM functions read or write structures in PEM format. In
154 this sense PEM format is simply base64 encoded data surrounded
157 For more details about the meaning of arguments see the
158 B<PEM FUNCTION ARGUMENTS> section.
160 Each operation has four functions associated with it. For
161 clarity the term "B<foobar> functions" will be used to collectively
162 refer to the PEM_read_bio_foobar(), PEM_read_foobar(),
163 PEM_write_bio_foobar() and PEM_write_foobar() functions.
165 The B<PrivateKey> functions read or write a private key in PEM format using an
166 EVP_PKEY structure. The write routines use PKCS#8 private key format and are
167 equivalent to PEM_write_bio_PKCS8PrivateKey().The read functions transparently
168 handle traditional and PKCS#8 format encrypted and unencrypted keys.
170 PEM_write_bio_PrivateKey_traditional() writes out a private key in legacy
171 "traditional" format.
173 PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private
174 key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using
175 PKCS#5 v2.0 password based encryption algorithms. The B<cipher> argument
176 specifies the encryption algorithm to use: unlike some other PEM routines the
177 encryption is applied at the PKCS#8 level and not in the PEM headers. If
178 B<cipher> is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo
179 structure is used instead.
181 PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
182 also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
183 it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
184 to use is specified in the B<nid> parameter and should be the NID of the
185 corresponding OBJECT IDENTIFIER (see NOTES section).
187 The B<PUBKEY> functions process a public key using an EVP_PKEY
188 structure. The public key is encoded as a SubjectPublicKeyInfo
191 The B<RSAPrivateKey> functions process an RSA private key using an
192 RSA structure. The write routines uses traditional format. The read
193 routines handles the same formats as the B<PrivateKey>
194 functions but an error occurs if the private key is not RSA.
196 The B<RSAPublicKey> functions process an RSA public key using an
197 RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey
200 The B<RSA_PUBKEY> functions also process an RSA public key using
201 an RSA structure. However the public key is encoded using a
202 SubjectPublicKeyInfo structure and an error occurs if the public
205 The B<DSAPrivateKey> functions process a DSA private key using a
206 DSA structure. The write routines uses traditional format. The read
207 routines handles the same formats as the B<PrivateKey>
208 functions but an error occurs if the private key is not DSA.
210 The B<DSA_PUBKEY> functions process a DSA public key using
211 a DSA structure. The public key is encoded using a
212 SubjectPublicKeyInfo structure and an error occurs if the public
215 The B<DSAparams> functions process DSA parameters using a DSA
216 structure. The parameters are encoded using a Dss-Parms structure
217 as defined in RFC2459.
219 The B<DHparams> functions process DH parameters using a DH
220 structure. The parameters are encoded using a PKCS#3 DHparameter
223 The B<X509> functions process an X509 certificate using an X509
224 structure. They will also process a trusted X509 certificate but
225 any trust settings are discarded.
227 The B<X509_AUX> functions process a trusted X509 certificate using
230 The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10
231 certificate request using an X509_REQ structure. The B<X509_REQ>
232 write functions use B<CERTIFICATE REQUEST> in the header whereas
233 the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST>
234 (as required by some CAs). The B<X509_REQ> read functions will
235 handle either form so there are no B<X509_REQ_NEW> read functions.
237 The B<X509_CRL> functions process an X509 CRL using an X509_CRL
240 The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7
243 =head1 PEM FUNCTION ARGUMENTS
245 The PEM functions have many common arguments.
247 The B<bp> BIO parameter (if present) specifies the BIO to read from
250 The B<fp> FILE parameter (if present) specifies the FILE pointer to
251 read from or write to.
253 The PEM read functions all take an argument B<TYPE **x> and return
254 a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function
255 uses. If B<x> is NULL then the parameter is ignored. If B<x> is not
256 NULL but B<*x> is NULL then the structure returned will be written
257 to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made
258 to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections).
259 Irrespective of the value of B<x> a pointer to the structure is always
260 returned (or NULL if an error occurred).
262 The PEM functions which write private keys take an B<enc> parameter
263 which specifies the encryption algorithm to use, encryption is done
264 at the PEM level. If this parameter is set to NULL then the private
265 key is written in unencrypted form.
267 The B<cb> argument is the callback to use when querying for the pass
268 phrase used for encrypted PEM structures (normally only private keys).
270 For the PEM write routines if the B<kstr> parameter is not NULL then
271 B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is
274 If the B<cb> parameters is set to NULL and the B<u> parameter is not
275 NULL then the B<u> parameter is interpreted as a null terminated string
276 to use as the passphrase. If both B<cb> and B<u> are NULL then the
277 default callback routine is used which will typically prompt for the
278 passphrase on the current terminal with echoing turned off.
280 The default passphrase callback is sometimes inappropriate (for example
281 in a GUI application) so an alternative can be supplied. The callback
282 routine has the following form:
284 int cb(char *buf, int size, int rwflag, void *u);
286 B<buf> is the buffer to write the passphrase to. B<size> is the maximum
287 length of the passphrase (i.e. the size of buf). B<rwflag> is a flag
288 which is set to 0 when reading and 1 when writing. A typical routine
289 will ask the user to verify the passphrase (for example by prompting
290 for it twice) if B<rwflag> is 1. The B<u> parameter has the same
291 value as the B<u> parameter passed to the PEM routine. It allows
292 arbitrary data to be passed to the callback by the application
293 (for example a window handle in a GUI application). The callback
294 B<must> return the number of characters in the passphrase or 0 if
299 Although the PEM routines take several arguments in almost all applications
300 most of them are set to 0 or NULL.
302 Read a certificate in PEM format from a BIO:
305 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
313 if (!PEM_read_bio_X509(bp, &x, 0, NULL)) {
317 Write a certificate to a BIO:
319 if (!PEM_write_bio_X509(bp, x)) {
323 Write a private key (using traditional format) to a BIO using
324 triple DES encryption, the pass phrase is prompted for:
326 if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) {
330 Write a private key (using PKCS#8 format) to a BIO using triple
331 DES encryption, using the pass phrase "hello":
333 if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) {
337 Read a private key from a BIO using a pass phrase callback:
339 key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
344 Skeleton pass phrase callback:
346 int pass_cb(char *buf, int size, int rwflag, void *u)
351 /* We'd probably do something else if 'rwflag' is 1 */
352 printf("Enter pass phrase for \"%s\"\n", (char *)u);
354 /* get pass phrase, length 'len' into 'tmp' */
362 memcpy(buf, tmp, len);
368 The old B<PrivateKey> write routines are retained for compatibility.
369 New applications should write private keys using the
370 PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
371 because they are more secure (they use an iteration count of 2048 whereas
372 the traditional routines use a count of 1) unless compatibility with older
373 versions of OpenSSL is important.
375 The B<PrivateKey> read routines can be used in all applications because
376 they handle all formats transparently.
378 A frequent cause of problems is attempting to use the PEM routines like
382 PEM_read_bio_X509(bp, &x, 0, NULL);
384 this is a bug because an attempt will be made to reuse the data at B<x>
385 which is an uninitialised pointer.
387 =head1 PEM ENCRYPTION FORMAT
389 These old B<PrivateKey> routines use a non standard technique for encryption.
391 The private key (or other data) takes the following form:
393 -----BEGIN RSA PRIVATE KEY-----
394 Proc-Type: 4,ENCRYPTED
395 DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
397 ...base64 encoded data...
398 -----END RSA PRIVATE KEY-----
400 The line beginning with I<Proc-Type> contains the version and the
401 protection on the encapsulated data. The line beginning I<DEK-Info>
402 contains two comma separated values: the encryption algorithm name as
403 used by EVP_get_cipherbyname() and an initialization vector used by the
404 cipher encoded as a set of hexadecimal digits. After those two lines is
405 the base64-encoded encrypted data.
407 The encryption key is derived using EVP_BytesToKey(). The cipher's
408 initialization vector is passed to EVP_BytesToKey() as the B<salt>
409 parameter. Internally, B<PKCS5_SALT_LEN> bytes of the salt are used
410 (regardless of the size of the initialization vector). The user's
411 password is passed to EVP_BytesToKey() using the B<data> and B<datal>
412 parameters. Finally, the library uses an iteration count of 1 for
415 The B<key> derived by EVP_BytesToKey() along with the original initialization
416 vector is then used to decrypt the encrypted data. The B<iv> produced by
417 EVP_BytesToKey() is not utilized or needed, and NULL should be passed to
420 The pseudo code to derive the key would look similar to:
422 EVP_CIPHER* cipher = EVP_des_ede3_cbc();
423 EVP_MD* md = EVP_md5();
425 unsigned int nkey = EVP_CIPHER_key_length(cipher);
426 unsigned int niv = EVP_CIPHER_iv_length(cipher);
427 unsigned char key[nkey];
428 unsigned char iv[niv];
430 memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv);
431 rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/);
436 /* On success, use key and iv to initialize the cipher */
440 The PEM read routines in some versions of OpenSSL will not correctly reuse
441 an existing structure. Therefore the following:
443 PEM_read_bio_X509(bp, &x, 0, NULL);
445 where B<x> already contains a valid certificate, may not work, whereas:
448 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
450 is guaranteed to work.
454 The read routines return either a pointer to the structure read or NULL
455 if an error occurred.
457 The write routines return 1 for success or 0 for failure.
461 The old Netscape certificate sequences were no longer documented
462 in OpenSSL 1.1; applications should use the PKCS7 standard instead
463 as they will be formally deprecated in a future releases.
467 L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)>
471 Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
473 Licensed under the OpenSSL license (the "License"). You may not use
474 this file except in compliance with the License. You can obtain a copy
475 in the file LICENSE in the source distribution or at
476 L<https://www.openssl.org/source/license.html>.