1pem(3) OpenSSL pem(3)
2
6 PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey,
7 PEM_write_bio_PrivateKey, PEM_write_PrivateKey,
8 PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey,
9 PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid,
10 PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY,
11 PEM_write_PUBKEY, PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey,
12 PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey,
13 PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey,
14 PEM_write_bio_RSAPublicKey, PEM_write_RSAPublicKey,
15 PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, PEM_write_bio_RSA_PUBKEY,
16 PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey,
17 PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey,
18 PEM_write_DSAPrivateKey, PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY,
19 PEM_write_bio_DSA_PUBKEY, PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams,
20 PEM_read_DSAparams, PEM_write_bio_DSAparams, PEM_write_DSAparams,
21 PEM_read_bio_DHparams, PEM_read_DHparams, PEM_write_bio_DHparams,
22 PEM_write_DHparams, PEM_read_bio_X509, PEM_read_X509,
23 PEM_write_bio_X509, PEM_write_X509, PEM_read_bio_X509_AUX,
24 PEM_read_X509_AUX, PEM_write_bio_X509_AUX, PEM_write_X509_AUX,
25 PEM_read_bio_X509_REQ, PEM_read_X509_REQ, PEM_write_bio_X509_REQ,
26 PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, PEM_write_X509_REQ_NEW,
27 PEM_read_bio_X509_CRL, PEM_read_X509_CRL, PEM_write_bio_X509_CRL,
28 PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7,
29 PEM_write_bio_PKCS7, PEM_write_PKCS7,
30 PEM_read_bio_NETSCAPE_CERT_SEQUENCE, PEM_read_NETSCAPE_CERT_SEQUENCE,
31 PEM_write_bio_NETSCAPE_CERT_SEQUENCE, PEM_write_NETSCAPE_CERT_SEQUENCE
32 - PEM routines
33
35 #include <openssl/pem.h>
36 EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
38 pem_password_cb *cb, void *u);
39 EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
41 pem_password_cb *cb, void *u);
42 int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
44 unsigned char *kstr, int klen,
45 pem_password_cb *cb, void *u);
46 int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
48 unsigned char *kstr, int klen,
49 pem_password_cb *cb, void *u);
50 int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
52 char *kstr, int klen,
53 pem_password_cb *cb, void *u);
54 int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
56 char *kstr, int klen,
57 pem_password_cb *cb, void *u);
58 int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
60 char *kstr, int klen,
61 pem_password_cb *cb, void *u);
62 int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
64 char *kstr, int klen,
65 pem_password_cb *cb, void *u);
66 EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
68 pem_password_cb *cb, void *u);
69 EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
71 pem_password_cb *cb, void *u);
72 int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
74 int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
75 RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
77 pem_password_cb *cb, void *u);
78 RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
80 pem_password_cb *cb, void *u);
81 int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,
83 unsigned char *kstr, int klen,
84 pem_password_cb *cb, void *u);
85 int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,
87 unsigned char *kstr, int klen,
88 pem_password_cb *cb, void *u);
89 RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
91 pem_password_cb *cb, void *u);
92 RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
94 pem_password_cb *cb, void *u);
95 int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
97 int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
99 RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
101 pem_password_cb *cb, void *u);
102 RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
104 pem_password_cb *cb, void *u);
105 int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
107 int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
109 DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
111 pem_password_cb *cb, void *u);
112 DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
114 pem_password_cb *cb, void *u);
115 int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,
117 unsigned char *kstr, int klen,
118 pem_password_cb *cb, void *u);
119 int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,
121 unsigned char *kstr, int klen,
122 pem_password_cb *cb, void *u);
123 DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
125 pem_password_cb *cb, void *u);
126 DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
128 pem_password_cb *cb, void *u);
129 int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
131 int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
133 DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
135 DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
137 int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
139 int PEM_write_DSAparams(FILE *fp, DSA *x);
141 DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
143 DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
145 int PEM_write_bio_DHparams(BIO *bp, DH *x);
147 int PEM_write_DHparams(FILE *fp, DH *x);
149 X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
151 X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
153 int PEM_write_bio_X509(BIO *bp, X509 *x);
155 int PEM_write_X509(FILE *fp, X509 *x);
157 X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
159 X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
161 int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
163 int PEM_write_X509_AUX(FILE *fp, X509 *x);
165 X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
167 pem_password_cb *cb, void *u);
168 X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
170 pem_password_cb *cb, void *u);
171 int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
173 int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
175 int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
177 int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
179 X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,
181 pem_password_cb *cb, void *u);
182 X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
183 pem_password_cb *cb, void *u);
184 int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x);
185 int PEM_write_X509_CRL(FILE *fp, X509_CRL *x);
186 PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
188 PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
190 int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
192 int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
194 NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,
196 NETSCAPE_CERT_SEQUENCE **x,
197 pem_password_cb *cb, void *u);
198 NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,
200 NETSCAPE_CERT_SEQUENCE **x,
201 pem_password_cb *cb, void *u);
202 int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);
204 int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x);
206
208 The PEM functions read or write structures in PEM format. In this sense
209 PEM format is simply base64 encoded data surrounded by header lines.
210 For more details about the meaning of arguments see the PEM FUNCTION
212 ARGUMENTS section.
213 Each operation has four functions associated with it. For clarity the
215 term "foobar functions" will be used to collectively refer to the
216 PEM_read_bio_foobar(), PEM_read_foobar(), PEM_write_bio_foobar() and
217 PEM_write_foobar() functions.
218 The PrivateKey functions read or write a private key in PEM format
220 using an EVP_PKEY structure. The write routines use "traditional"
221 private key format and can handle both RSA and DSA private keys. The
222 read functions can additionally transparently handle PKCS#8 format
223 encrypted and unencrypted keys too.
224 PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a
226 private key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo
227 format using PKCS#5 v2.0 password based encryption algorithms. The
228 cipher argument specifies the encryption algoritm to use: unlike all
229 other PEM routines the encryption is applied at the PKCS#8 level and
230 not in the PEM headers. If cipher is NULL then no encryption is used
231 and a PKCS#8 PrivateKeyInfo structure is used instead.
232 PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
234 also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo
235 however it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead.
236 The algorithm to use is specified in the nid parameter and should be
237 the NID of the corresponding OBJECT IDENTIFIER (see NOTES section).
238 The PUBKEY functions process a public key using an EVP_PKEY structure.
240 The public key is encoded as a SubjectPublicKeyInfo structure.
241 The RSAPrivateKey functions process an RSA private key using an RSA
243 structure. It handles the same formats as the PrivateKey functions but
244 an error occurs if the private key is not RSA.
245 The RSAPublicKey functions process an RSA public key using an RSA
247 structure. The public key is encoded using a PKCS#1 RSAPublicKey
248 structure.
249 The RSA_PUBKEY functions also process an RSA public key using an RSA
251 structure. However the public key is encoded using a
252 SubjectPublicKeyInfo structure and an error occurs if the public key is
253 not RSA.
254 The DSAPrivateKey functions process a DSA private key using a DSA
256 structure. It handles the same formats as the PrivateKey functions but
257 an error occurs if the private key is not DSA.
258 The DSA_PUBKEY functions process a DSA public key using a DSA
260 structure. The public key is encoded using a SubjectPublicKeyInfo
261 structure and an error occurs if the public key is not DSA.
262 The DSAparams functions process DSA parameters using a DSA structure.
264 The parameters are encoded using a foobar structure.
265 The DHparams functions process DH parameters using a DH structure. The
267 parameters are encoded using a PKCS#3 DHparameter structure.
268 The X509 functions process an X509 certificate using an X509 structure.
270 They will also process a trusted X509 certificate but any trust
271 settings are discarded.
272 The X509_AUX functions process a trusted X509 certificate using an X509
274 structure.
275 The X509_REQ and X509_REQ_NEW functions process a PKCS#10 certificate
277 request using an X509_REQ structure. The X509_REQ write functions use
278 CERTIFICATE REQUEST in the header whereas the X509_REQ_NEW functions
279 use NEW CERTIFICATE REQUEST (as required by some CAs). The X509_REQ
280 read functions will handle either form so there are no X509_REQ_NEW
281 read functions.
282 The X509_CRL functions process an X509 CRL using an X509_CRL structure.
284 The PKCS7 functions process a PKCS#7 ContentInfo using a PKCS7
286 structure.
287 The NETSCAPE_CERT_SEQUENCE functions process a Netscape Certificate
289 Sequence using a NETSCAPE_CERT_SEQUENCE structure.
290
292 The PEM functions have many common arguments.
293 The bp BIO parameter (if present) specifies the BIO to read from or
295 write to.
296 The fp FILE parameter (if present) specifies the FILE pointer to read
298 from or write to.
299 The PEM read functions all take an argument TYPE **x and return a TYPE
301 * pointer. Where TYPE is whatever structure the function uses. If x is
302 NULL then the parameter is ignored. If x is not NULL but *x is NULL
303 then the structure returned will be written to *x. If neither x nor *x
304 is NULL then an attempt is made to reuse the structure at *x (but see
305 BUGS and EXAMPLES sections). Irrespective of the value of x a pointer
306 to the structure is always returned (or NULL if an error occurred).
307 The PEM functions which write private keys take an enc parameter which
309 specifies the encryption algorithm to use, encryption is done at the
310 PEM level. If this parameter is set to NULL then the private key is
311 written in unencrypted form.
312 The cb argument is the callback to use when querying for the pass
314 phrase used for encrypted PEM structures (normally only private keys).
315 For the PEM write routines if the kstr parameter is not NULL then klen
317 bytes at kstr are used as the passphrase and cb is ignored.
318 If the cb parameters is set to NULL and the u parameter is not NULL
320 then the u parameter is interpreted as a null terminated string to use
321 as the passphrase. If both cb and u are NULL then the default callback
322 routine is used which will typically prompt for the passphrase on the
323 current terminal with echoing turned off.
324 The default passphrase callback is sometimes inappropriate (for example
326 in a GUI application) so an alternative can be supplied. The callback
327 routine has the following form:
328 int cb(char *buf, int size, int rwflag, void *u);
330 buf is the buffer to write the passphrase to. size is the maximum
332 length of the passphrase (i.e. the size of buf). rwflag is a flag which
333 is set to 0 when reading and 1 when writing. A typical routine will ask
334 the user to verify the passphrase (for example by prompting for it
335 twice) if rwflag is 1. The u parameter has the same value as the u
336 parameter passed to the PEM routine. It allows arbitrary data to be
337 passed to the callback by the application (for example a window handle
338 in a GUI application). The callback must return the number of
339 characters in the passphrase or 0 if an error occurred.
340
342 Although the PEM routines take several arguments in almost all
343 applications most of them are set to 0 or NULL.
344 Read a certificate in PEM format from a BIO:
346 X509 *x;
348 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
349 if (x == NULL)
350 {
351 /* Error */
352 }
353 Alternative method:
355 X509 *x = NULL;
357 if (!PEM_read_bio_X509(bp, &x, 0, NULL))
358 {
359 /* Error */
360 }
361 Write a certificate to a BIO:
363 if (!PEM_write_bio_X509(bp, x))
365 {
366 /* Error */
367 }
368 Write an unencrypted private key to a FILE pointer:
370 if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL))
372 {
373 /* Error */
374 }
375 Write a private key (using traditional format) to a BIO using triple
377 DES encryption, the pass phrase is prompted for:
378 if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
380 {
381 /* Error */
382 }
383 Write a private key (using PKCS#8 format) to a BIO using triple DES
385 encryption, using the pass phrase "hello":
386 if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello"))
388 {
389 /* Error */
390 }
391 Read a private key from a BIO using the pass phrase "hello":
393 key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
395 if (key == NULL)
396 {
397 /* Error */
398 }
399 Read a private key from a BIO using a pass phrase callback:
401 key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
403 if (key == NULL)
404 {
405 /* Error */
406 }
407 Skeleton pass phrase callback:
409 int pass_cb(char *buf, int size, int rwflag, void *u);
411 {
412 int len;
413 char *tmp;
414 /* We'd probably do something else if 'rwflag' is 1 */
415 printf("Enter pass phrase for \"%s\"\n", u);
416 /* get pass phrase, length 'len' into 'tmp' */
418 tmp = "hello";
419 len = strlen(tmp);
420 if (len <= 0) return 0;
422 /* if too long, truncate */
423 if (len > size) len = size;
424 memcpy(buf, tmp, len);
425 return len;
426 }
427
429 The old PrivateKey write routines are retained for compatibility. New
430 applications should write private keys using the
431 PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
432 because they are more secure (they use an iteration count of 2048
433 whereas the traditional routines use a count of 1) unless compatibility
434 with older versions of OpenSSL is important.
435 The PrivateKey read routines can be used in all applications because
437 they handle all formats transparently.
438 A frequent cause of problems is attempting to use the PEM routines like
440 this:
441 X509 *x;
443 PEM_read_bio_X509(bp, &x, 0, NULL);
444 this is a bug because an attempt will be made to reuse the data at x
446 which is an uninitialised pointer.
447
449 This old PrivateKey routines use a non standard technique for
450 encryption.
451 The private key (or other data) takes the following form:
453 -----BEGIN RSA PRIVATE KEY-----
455 Proc-Type: 4,ENCRYPTED
456 DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
457 ...base64 encoded data...
459 -----END RSA PRIVATE KEY-----
460 The line beginning DEK-Info contains two comma separated pieces of
462 information: the encryption algorithm name as used by
463 EVP_get_cipherbyname() and an 8 byte salt encoded as a set of
464 hexadecimal digits.
465 After this is the base64 encoded encrypted data.
467 The encryption key is determined using EVP_bytestokey(), using salt and
469 an iteration count of 1. The IV used is the value of salt and *not* the
470 IV returned by EVP_bytestokey().
471
473 The PEM read routines in some versions of OpenSSL will not correctly
474 reuse an existing structure. Therefore the following:
475 PEM_read_bio_X509(bp, &x, 0, NULL);
477 where x already contains a valid certificate, may not work, whereas:
479 X509_free(x);
481 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
482 is guaranteed to work.
484
486 The read routines return either a pointer to the structure read or NULL
487 if an error occurred.
488 The write routines return 1 for success or 0 for failure.
4901.0.0e 2009-06-02 pem(3)