5 PEM, 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
9 #include <openssl/pem.h>
11 EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
12 pem_password_cb *cb, void *u);
14 EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
15 pem_password_cb *cb, void *u);
17 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);
21 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);
25 int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
27 pem_password_cb *cb, void *u);
29 int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
31 pem_password_cb *cb, void *u);
33 int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
35 pem_password_cb *cb, void *u);
37 int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
39 pem_password_cb *cb, void *u);
41 EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
42 pem_password_cb *cb, void *u);
44 EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
45 pem_password_cb *cb, void *u);
47 int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
48 int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
50 RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
51 pem_password_cb *cb, void *u);
53 RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
54 pem_password_cb *cb, void *u);
56 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);
60 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);
64 RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
65 pem_password_cb *cb, void *u);
67 RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
68 pem_password_cb *cb, void *u);
70 int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
72 int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
74 RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
75 pem_password_cb *cb, void *u);
77 RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
78 pem_password_cb *cb, void *u);
80 int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
82 int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
84 DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
85 pem_password_cb *cb, void *u);
87 DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
88 pem_password_cb *cb, void *u);
90 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);
94 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);
98 DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
99 pem_password_cb *cb, void *u);
101 DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
102 pem_password_cb *cb, void *u);
104 int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
106 int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
108 DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
110 DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
112 int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
114 int PEM_write_DSAparams(FILE *fp, DSA *x);
116 DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
118 DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
120 int PEM_write_bio_DHparams(BIO *bp, DH *x);
122 int PEM_write_DHparams(FILE *fp, DH *x);
124 X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
126 X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
128 int PEM_write_bio_X509(BIO *bp, X509 *x);
130 int PEM_write_X509(FILE *fp, X509 *x);
132 X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
134 X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
136 int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
138 int PEM_write_X509_AUX(FILE *fp, X509 *x);
140 X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
141 pem_password_cb *cb, void *u);
143 X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
144 pem_password_cb *cb, void *u);
146 int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
148 int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
150 int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
152 int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
154 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);
161 PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
163 PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
165 int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
167 int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
169 NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,
170 NETSCAPE_CERT_SEQUENCE **x,
171 pem_password_cb *cb, void *u);
173 NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,
174 NETSCAPE_CERT_SEQUENCE **x,
175 pem_password_cb *cb, void *u);
177 int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);
179 int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x);
183 The PEM functions read or write structures in PEM format. In
184 this sense PEM format is simply base64 encoded data surrounded
187 For more details about the meaning of arguments see the
188 B<PEM FUNCTION ARGUMENTS> section.
190 Each operation has four functions associated with it. For
191 clarity the term "B<foobar> functions" will be used to collectively
192 refer to the PEM_read_bio_foobar(), PEM_read_foobar(),
193 PEM_write_bio_foobar() and PEM_write_foobar() functions.
195 The B<PrivateKey> functions read or write a private key in
196 PEM format using an EVP_PKEY structure. The write routines use
197 "traditional" private key format and can handle both RSA and DSA
198 private keys. The read functions can additionally transparently
199 handle PKCS#8 format encrypted and unencrypted keys too.
201 PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey()
202 write a private key in an EVP_PKEY structure in PKCS#8
203 EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption
204 algorithms. The B<cipher> argument specifies the encryption algorithm to
205 use: unlike all other PEM routines the encryption is applied at the
206 PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no
207 encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead.
209 PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
210 also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
211 it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
212 to use is specified in the B<nid> parameter and should be the NID of the
213 corresponding OBJECT IDENTIFIER (see NOTES section).
215 The B<PUBKEY> functions process a public key using an EVP_PKEY
216 structure. The public key is encoded as a SubjectPublicKeyInfo
219 The B<RSAPrivateKey> functions process an RSA private key using an
220 RSA structure. It handles the same formats as the B<PrivateKey>
221 functions but an error occurs if the private key is not RSA.
223 The B<RSAPublicKey> functions process an RSA public key using an
224 RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey
227 The B<RSA_PUBKEY> functions also process an RSA public key using
228 an RSA structure. However the public key is encoded using a
229 SubjectPublicKeyInfo structure and an error occurs if the public
232 The B<DSAPrivateKey> functions process a DSA private key using a
233 DSA structure. It handles the same formats as the B<PrivateKey>
234 functions but an error occurs if the private key is not DSA.
236 The B<DSA_PUBKEY> functions process a DSA public key using
237 a DSA structure. The public key is encoded using a
238 SubjectPublicKeyInfo structure and an error occurs if the public
241 The B<DSAparams> functions process DSA parameters using a DSA
242 structure. The parameters are encoded using a foobar structure.
244 The B<DHparams> functions process DH parameters using a DH
245 structure. The parameters are encoded using a PKCS#3 DHparameter
248 The B<X509> functions process an X509 certificate using an X509
249 structure. They will also process a trusted X509 certificate but
250 any trust settings are discarded.
252 The B<X509_AUX> functions process a trusted X509 certificate using
255 The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10
256 certificate request using an X509_REQ structure. The B<X509_REQ>
257 write functions use B<CERTIFICATE REQUEST> in the header whereas
258 the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST>
259 (as required by some CAs). The B<X509_REQ> read functions will
260 handle either form so there are no B<X509_REQ_NEW> read functions.
262 The B<X509_CRL> functions process an X509 CRL using an X509_CRL
265 The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7
268 The B<NETSCAPE_CERT_SEQUENCE> functions process a Netscape Certificate
269 Sequence using a NETSCAPE_CERT_SEQUENCE structure.
271 =head1 PEM FUNCTION ARGUMENTS
273 The PEM functions have many common arguments.
275 The B<bp> BIO parameter (if present) specifies the BIO to read from
278 The B<fp> FILE parameter (if present) specifies the FILE pointer to
279 read from or write to.
281 The PEM read functions all take an argument B<TYPE **x> and return
282 a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function
283 uses. If B<x> is NULL then the parameter is ignored. If B<x> is not
284 NULL but B<*x> is NULL then the structure returned will be written
285 to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made
286 to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections).
287 Irrespective of the value of B<x> a pointer to the structure is always
288 returned (or NULL if an error occurred).
290 The PEM functions which write private keys take an B<enc> parameter
291 which specifies the encryption algorithm to use, encryption is done
292 at the PEM level. If this parameter is set to NULL then the private
293 key is written in unencrypted form.
295 The B<cb> argument is the callback to use when querying for the pass
296 phrase used for encrypted PEM structures (normally only private keys).
298 For the PEM write routines if the B<kstr> parameter is not NULL then
299 B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is
302 If the B<cb> parameters is set to NULL and the B<u> parameter is not
303 NULL then the B<u> parameter is interpreted as a null terminated string
304 to use as the passphrase. If both B<cb> and B<u> are NULL then the
305 default callback routine is used which will typically prompt for the
306 passphrase on the current terminal with echoing turned off.
308 The default passphrase callback is sometimes inappropriate (for example
309 in a GUI application) so an alternative can be supplied. The callback
310 routine has the following form:
312 int cb(char *buf, int size, int rwflag, void *u);
314 B<buf> is the buffer to write the passphrase to. B<size> is the maximum
315 length of the passphrase (i.e. the size of buf). B<rwflag> is a flag
316 which is set to 0 when reading and 1 when writing. A typical routine
317 will ask the user to verify the passphrase (for example by prompting
318 for it twice) if B<rwflag> is 1. The B<u> parameter has the same
319 value as the B<u> parameter passed to the PEM routine. It allows
320 arbitrary data to be passed to the callback by the application
321 (for example a window handle in a GUI application). The callback
322 B<must> return the number of characters in the passphrase or 0 if
327 Although the PEM routines take several arguments in almost all applications
328 most of them are set to 0 or NULL.
330 Read a certificate in PEM format from a BIO:
333 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
342 if (!PEM_read_bio_X509(bp, &x, 0, NULL))
347 Write a certificate to a BIO:
349 if (!PEM_write_bio_X509(bp, x))
354 Write an unencrypted private key to a FILE pointer:
356 if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL))
361 Write a private key (using traditional format) to a BIO using
362 triple DES encryption, the pass phrase is prompted for:
364 if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
369 Write a private key (using PKCS#8 format) to a BIO using triple
370 DES encryption, using the pass phrase "hello":
372 if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello"))
377 Read a private key from a BIO using the pass phrase "hello":
379 key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
385 Read a private key from a BIO using a pass phrase callback:
387 key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
393 Skeleton pass phrase callback:
395 int pass_cb(char *buf, int size, int rwflag, void *u);
399 /* We'd probably do something else if 'rwflag' is 1 */
400 printf("Enter pass phrase for \"%s\"\n", u);
402 /* get pass phrase, length 'len' into 'tmp' */
406 if (len <= 0) return 0;
407 /* if too long, truncate */
408 if (len > size) len = size;
409 memcpy(buf, tmp, len);
415 The old B<PrivateKey> write routines are retained for compatibility.
416 New applications should write private keys using the
417 PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
418 because they are more secure (they use an iteration count of 2048 whereas
419 the traditional routines use a count of 1) unless compatibility with older
420 versions of OpenSSL is important.
422 The B<PrivateKey> read routines can be used in all applications because
423 they handle all formats transparently.
425 A frequent cause of problems is attempting to use the PEM routines like
429 PEM_read_bio_X509(bp, &x, 0, NULL);
431 this is a bug because an attempt will be made to reuse the data at B<x>
432 which is an uninitialised pointer.
434 =head1 PEM ENCRYPTION FORMAT
436 This old B<PrivateKey> routines use a non standard technique for encryption.
438 The private key (or other data) takes the following form:
440 -----BEGIN RSA PRIVATE KEY-----
441 Proc-Type: 4,ENCRYPTED
442 DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
444 ...base64 encoded data...
445 -----END RSA PRIVATE KEY-----
447 The line beginning DEK-Info contains two comma separated pieces of information:
448 the encryption algorithm name as used by EVP_get_cipherbyname() and an 8
449 byte B<salt> encoded as a set of hexadecimal digits.
451 After this is the base64 encoded encrypted data.
453 The encryption key is determined using EVP_BytesToKey(), using B<salt> and an
454 iteration count of 1. The IV used is the value of B<salt> and *not* the IV
455 returned by EVP_BytesToKey().
459 The PEM read routines in some versions of OpenSSL will not correctly reuse
460 an existing structure. Therefore the following:
462 PEM_read_bio_X509(bp, &x, 0, NULL);
464 where B<x> already contains a valid certificate, may not work, whereas:
467 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
469 is guaranteed to work.
473 The read routines return either a pointer to the structure read or NULL
474 if an error occurred.
476 The write routines return 1 for success or 0 for failure.
480 L<EVP_get_cipherbyname(3)|EVP_get_cipherbyname>, L<EVP_BytesToKey(3)|EVP_BytesToKey(3)>