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