1pem(3) OpenSSL pem(3)
2
6 PEM - PEM routines
7
9 #include <openssl/pem.h>
10 EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
12 pem_password_cb *cb, void *u);
13 EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
15 pem_password_cb *cb, void *u);
16 int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
18 unsigned char *kstr, int klen,
19 pem_password_cb *cb, void *u);
20 int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
22 unsigned char *kstr, int klen,
23 pem_password_cb *cb, void *u);
24 int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
26 char *kstr, int klen,
27 pem_password_cb *cb, void *u);
28 int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
30 char *kstr, int klen,
31 pem_password_cb *cb, void *u);
32 int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
34 char *kstr, int klen,
35 pem_password_cb *cb, void *u);
36 int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
38 char *kstr, int klen,
39 pem_password_cb *cb, void *u);
40 EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
42 pem_password_cb *cb, void *u);
43 EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
45 pem_password_cb *cb, void *u);
46 int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
48 int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
49 RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
51 pem_password_cb *cb, void *u);
52 RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
54 pem_password_cb *cb, void *u);
55 int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,
57 unsigned char *kstr, int klen,
58 pem_password_cb *cb, void *u);
59 int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,
61 unsigned char *kstr, int klen,
62 pem_password_cb *cb, void *u);
63 RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
65 pem_password_cb *cb, void *u);
66 RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
68 pem_password_cb *cb, void *u);
69 int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
71 int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
73 RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
75 pem_password_cb *cb, void *u);
76 RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
78 pem_password_cb *cb, void *u);
79 int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
81 int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
83 DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
85 pem_password_cb *cb, void *u);
86 DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
88 pem_password_cb *cb, void *u);
89 int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,
91 unsigned char *kstr, int klen,
92 pem_password_cb *cb, void *u);
93 int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,
95 unsigned char *kstr, int klen,
96 pem_password_cb *cb, void *u);
97 DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
99 pem_password_cb *cb, void *u);
100 DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
102 pem_password_cb *cb, void *u);
103 int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
105 int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
107 DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
109 DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
111 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);
117 DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
119 int PEM_write_bio_DHparams(BIO *bp, DH *x);
121 int PEM_write_DHparams(FILE *fp, DH *x);
123 X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
125 X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
127 int PEM_write_bio_X509(BIO *bp, X509 *x);
129 int PEM_write_X509(FILE *fp, X509 *x);
131 X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
133 X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
135 int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
137 int PEM_write_X509_AUX(FILE *fp, X509 *x);
139 X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
141 pem_password_cb *cb, void *u);
142 X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
144 pem_password_cb *cb, void *u);
145 int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
147 int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
149 int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
151 int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
153 X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,
155 pem_password_cb *cb, void *u);
156 X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
157 pem_password_cb *cb, void *u);
158 int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x);
159 int PEM_write_X509_CRL(FILE *fp, X509_CRL *x);
160 PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
162 PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
164 int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
166 int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
168 NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,
170 NETSCAPE_CERT_SEQUENCE **x,
171 pem_password_cb *cb, void *u);
172 NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,
174 NETSCAPE_CERT_SEQUENCE **x,
175 pem_password_cb *cb, void *u);
176 int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);
178 int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x);
180
182 The PEM functions read or write structures in PEM format. In this sense
183 PEM format is simply base64 encoded data surrounded by header lines.
184 For more details about the meaning of arguments see the PEM FUNCTION
186 ARGUMENTS section.
187 Each operation has four functions associated with it. For clarity the
189 term "foobar functions" will be used to collectively refer to the
190 PEM_read_bio_foobar(), PEM_read_foobar(), PEM_write_bio_foobar() and
191 PEM_write_foobar() functions.
192 The PrivateKey functions read or write a private key in PEM format
194 using an EVP_PKEY structure. The write routines use "traditional" pri‐
195 vate key format and can handle both RSA and DSA private keys. The read
196 functions can additionally transparently handle PKCS#8 format encrypted
197 and unencrypted keys too.
198 PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a
200 private key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo
201 format using PKCS#5 v2.0 password based encryption algorithms. The
202 cipher argument specifies the encryption algoritm to use: unlike all
203 other PEM routines the encryption is applied at the PKCS#8 level and
204 not in the PEM headers. If cipher is NULL then no encryption is used
205 and a PKCS#8 PrivateKeyInfo structure is used instead.
206 PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
208 also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo how‐
209 ever it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The
210 algorithm to use is specified in the nid parameter and should be the
211 NID of the corresponding OBJECT IDENTIFIER (see NOTES section).
212 The PUBKEY functions process a public key using an EVP_PKEY structure.
214 The public key is encoded as a SubjectPublicKeyInfo structure.
215 The RSAPrivateKey functions process an RSA private key using an RSA
217 structure. It handles the same formats as the PrivateKey functions but
218 an error occurs if the private key is not RSA.
219 The RSAPublicKey functions process an RSA public key using an RSA
221 structure. The public key is encoded using a PKCS#1 RSAPublicKey struc‐
222 ture.
223 The RSA_PUBKEY functions also process an RSA public key using an RSA
225 structure. However the public key is encoded using a SubjectPublicKey‐
226 Info structure and an error occurs if the public key is not RSA.
227 The DSAPrivateKey functions process a DSA private key using a DSA
229 structure. It handles the same formats as the PrivateKey functions but
230 an error occurs if the private key is not DSA.
231 The DSA_PUBKEY functions process a DSA public key using a DSA struc‐
233 ture. The public key is encoded using a SubjectPublicKeyInfo structure
234 and an error occurs if the public key is not DSA.
235 The DSAparams functions process DSA parameters using a DSA structure.
237 The parameters are encoded using a foobar structure.
238 The DHparams functions process DH parameters using a DH structure. The
240 parameters are encoded using a PKCS#3 DHparameter structure.
241 The X509 functions process an X509 certificate using an X509 structure.
243 They will also process a trusted X509 certificate but any trust set‐
244 tings are discarded.
245 The X509_AUX functions process a trusted X509 certificate using an X509
247 structure.
248 The X509_REQ and X509_REQ_NEW functions process a PKCS#10 certificate
250 request using an X509_REQ structure. The X509_REQ write functions use
251 CERTIFICATE REQUEST in the header whereas the X509_REQ_NEW functions
252 use NEW CERTIFICATE REQUEST (as required by some CAs). The X509_REQ
253 read functions will handle either form so there are no X509_REQ_NEW
254 read functions.
255 The X509_CRL functions process an X509 CRL using an X509_CRL structure.
257 The PKCS7 functions process a PKCS#7 ContentInfo using a PKCS7 struc‐
259 ture.
260 The NETSCAPE_CERT_SEQUENCE functions process a Netscape Certificate
262 Sequence using a NETSCAPE_CERT_SEQUENCE structure.
263
265 The PEM functions have many common arguments.
266 The bp BIO parameter (if present) specifies the BIO to read from or
268 write to.
269 The fp FILE parameter (if present) specifies the FILE pointer to read
271 from or write to.
272 The PEM read functions all take an argument TYPE **x and return a TYPE
274 * pointer. Where TYPE is whatever structure the function uses. If x is
275 NULL then the parameter is ignored. If x is not NULL but *x is NULL
276 then the structure returned will be written to *x. If neither x nor *x
277 is NULL then an attempt is made to reuse the structure at *x (but see
278 BUGS and EXAMPLES sections). Irrespective of the value of x a pointer
279 to the structure is always returned (or NULL if an error occurred).
280 The PEM functions which write private keys take an enc parameter which
282 specifies the encryption algorithm to use, encryption is done at the
283 PEM level. If this parameter is set to NULL then the private key is
284 written in unencrypted form.
285 The cb argument is the callback to use when querying for the pass
287 phrase used for encrypted PEM structures (normally only private keys).
288 For the PEM write routines if the kstr parameter is not NULL then klen
290 bytes at kstr are used as the passphrase and cb is ignored.
291 If the cb parameters is set to NULL and the u parameter is not NULL
293 then the u parameter is interpreted as a null terminated string to use
294 as the passphrase. If both cb and u are NULL then the default callback
295 routine is used which will typically prompt for the passphrase on the
296 current terminal with echoing turned off.
297 The default passphrase callback is sometimes inappropriate (for example
299 in a GUI application) so an alternative can be supplied. The callback
300 routine has the following form:
301 int cb(char *buf, int size, int rwflag, void *u);
303 buf is the buffer to write the passphrase to. size is the maximum
305 length of the passphrase (i.e. the size of buf). rwflag is a flag which
306 is set to 0 when reading and 1 when writing. A typical routine will ask
307 the user to verify the passphrase (for example by prompting for it
308 twice) if rwflag is 1. The u parameter has the same value as the u
309 parameter passed to the PEM routine. It allows arbitrary data to be
310 passed to the callback by the application (for example a window handle
311 in a GUI application). The callback must return the number of charac‐
312 ters in the passphrase or 0 if an error occurred.
313
315 Although the PEM routines take several arguments in almost all applica‐
316 tions most of them are set to 0 or NULL.
317 Read a certificate in PEM format from a BIO:
319 X509 *x;
321 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
322 if (x == NULL)
323 {
324 /* Error */
325 }
326 Alternative method:
328 X509 *x = NULL;
330 if (!PEM_read_bio_X509(bp, &x, 0, NULL))
331 {
332 /* Error */
333 }
334 Write a certificate to a BIO:
336 if (!PEM_write_bio_X509(bp, x))
338 {
339 /* Error */
340 }
341 Write an unencrypted private key to a FILE pointer:
343 if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL))
345 {
346 /* Error */
347 }
348 Write a private key (using traditional format) to a BIO using triple
350 DES encryption, the pass phrase is prompted for:
351 if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
353 {
354 /* Error */
355 }
356 Write a private key (using PKCS#8 format) to a BIO using triple DES
358 encryption, using the pass phrase "hello":
359 if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello"))
361 {
362 /* Error */
363 }
364 Read a private key from a BIO using the pass phrase "hello":
366 key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
368 if (key == NULL)
369 {
370 /* Error */
371 }
372 Read a private key from a BIO using a pass phrase callback:
374 key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
376 if (key == NULL)
377 {
378 /* Error */
379 }
380 Skeleton pass phrase callback:
382 int pass_cb(char *buf, int size, int rwflag, void *u);
384 {
385 int len;
386 char *tmp;
387 /* We'd probably do something else if 'rwflag' is 1 */
388 printf("Enter pass phrase for \"%s\"\n", u);
389 /* get pass phrase, length 'len' into 'tmp' */
391 tmp = "hello";
392 len = strlen(tmp);
393 if (len <= 0) return 0;
395 /* if too long, truncate */
396 if (len > size) len = size;
397 memcpy(buf, tmp, len);
398 return len;
399 }
400
402 The old PrivateKey write routines are retained for compatibility. New
403 applications should write private keys using the
404 PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
405 because they are more secure (they use an iteration count of 2048
406 whereas the traditional routines use a count of 1) unless compatibility
407 with older versions of OpenSSL is important.
408 The PrivateKey read routines can be used in all applications because
410 they handle all formats transparently.
411 A frequent cause of problems is attempting to use the PEM routines like
413 this:
414 X509 *x;
416 PEM_read_bio_X509(bp, &x, 0, NULL);
417 this is a bug because an attempt will be made to reuse the data at x
419 which is an uninitialised pointer.
420
422 This old PrivateKey routines use a non standard technique for encryp‐
423 tion.
424 The private key (or other data) takes the following form:
426 -----BEGIN RSA PRIVATE KEY-----
428 Proc-Type: 4,ENCRYPTED
429 DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
430 ...base64 encoded data...
432 -----END RSA PRIVATE KEY-----
433 The line beginning DEK-Info contains two comma separated pieces of
435 information: the encryption algorithm name as used by EVP_get_cipherby‐
436 name() and an 8 byte salt encoded as a set of hexadecimal digits.
437 After this is the base64 encoded encrypted data.
439 The encryption key is determined using EVP_bytestokey(), using salt and
441 an iteration count of 1. The IV used is the value of salt and *not* the
442 IV returned by EVP_bytestokey().
443
445 The PEM read routines in some versions of OpenSSL will not correctly
446 reuse an existing structure. Therefore the following:
447 PEM_read_bio_X509(bp, &x, 0, NULL);
449 where x already contains a valid certificate, may not work, whereas:
451 X509_free(x);
453 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
454 is guaranteed to work.
456
458 The read routines return either a pointer to the structure read or NULL
459 if an error occurred.
460 The write routines return 1 for success or 0 for failure.
4620.9.8b 2004-03-21 pem(3)