pem(3ssl)

1pem(3)                              OpenSSL                             pem(3)
2
3
4

NAME

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

SYNOPSIS

35        #include <openssl/pem.h>
36
37        EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
38                                               pem_password_cb *cb, void *u);
39
40        EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
41                                               pem_password_cb *cb, void *u);
42
43        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
47        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
51        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
55        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
59        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
63        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
67        EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
68                                               pem_password_cb *cb, void *u);
69
70        EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
71                                               pem_password_cb *cb, void *u);
72
73        int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
74        int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
75
76        RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
77                                               pem_password_cb *cb, void *u);
78
79        RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
80                                               pem_password_cb *cb, void *u);
81
82        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
86        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
90        RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
91                                               pem_password_cb *cb, void *u);
92
93        RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
94                                               pem_password_cb *cb, void *u);
95
96        int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
97
98        int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
99
100        RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
101                                               pem_password_cb *cb, void *u);
102
103        RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
104                                               pem_password_cb *cb, void *u);
105
106        int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
107
108        int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
109
110        DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
111                                               pem_password_cb *cb, void *u);
112
113        DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
114                                               pem_password_cb *cb, void *u);
115
116        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
120        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
124        DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
125                                               pem_password_cb *cb, void *u);
126
127        DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
128                                               pem_password_cb *cb, void *u);
129
130        int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
131
132        int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
133
134        DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
135
136        DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
137
138        int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
139
140        int PEM_write_DSAparams(FILE *fp, DSA *x);
141
142        DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
143
144        DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
145
146        int PEM_write_bio_DHparams(BIO *bp, DH *x);
147
148        int PEM_write_DHparams(FILE *fp, DH *x);
149
150        X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
151
152        X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
153
154        int PEM_write_bio_X509(BIO *bp, X509 *x);
155
156        int PEM_write_X509(FILE *fp, X509 *x);
157
158        X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
159
160        X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
161
162        int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
163
164        int PEM_write_X509_AUX(FILE *fp, X509 *x);
165
166        X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
167                                               pem_password_cb *cb, void *u);
168
169        X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
170                                               pem_password_cb *cb, void *u);
171
172        int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
173
174        int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
175
176        int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
177
178        int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
179
180        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
187        PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
188
189        PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
190
191        int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
192
193        int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
194
195        NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,
196                                                       NETSCAPE_CERT_SEQUENCE **x,
197                                                       pem_password_cb *cb, void *u);
198
199        NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,
200                                                       NETSCAPE_CERT_SEQUENCE **x,
201                                                       pem_password_cb *cb, void *u);
202
203        int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);
204
205        int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x);
206

DESCRIPTION

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
211       For more details about the meaning of arguments see the PEM FUNCTION
212       ARGUMENTS section.
213
214       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
219       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
225       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 algorithm 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
233       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
239       The PUBKEY functions process a public key using an EVP_PKEY structure.
240       The public key is encoded as a SubjectPublicKeyInfo structure.
241
242       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
246       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
250       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
255       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
259       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
263       The DSAparams functions process DSA parameters using a DSA structure.
264       The parameters are encoded using a Dss-Parms structure as defined in
265       RFC2459.
266
267       The DHparams functions process DH parameters using a DH structure. The
268       parameters are encoded using a PKCS#3 DHparameter structure.
269
270       The X509 functions process an X509 certificate using an X509 structure.
271       They will also process a trusted X509 certificate but any trust
272       settings are discarded.
273
274       The X509_AUX functions process a trusted X509 certificate using an X509
275       structure.
276
277       The X509_REQ and X509_REQ_NEW functions process a PKCS#10 certificate
278       request using an X509_REQ structure. The X509_REQ write functions use
279       CERTIFICATE REQUEST in the header whereas the X509_REQ_NEW functions
280       use NEW CERTIFICATE REQUEST (as required by some CAs). The X509_REQ
281       read functions will handle either form so there are no X509_REQ_NEW
282       read functions.
283
284       The X509_CRL functions process an X509 CRL using an X509_CRL structure.
285
286       The PKCS7 functions process a PKCS#7 ContentInfo using a PKCS7
287       structure.
288
289       The NETSCAPE_CERT_SEQUENCE functions process a Netscape Certificate
290       Sequence using a NETSCAPE_CERT_SEQUENCE structure.
291

PEM FUNCTION ARGUMENTS

293       The PEM functions have many common arguments.
294
295       The bp BIO parameter (if present) specifies the BIO to read from or
296       write to.
297
298       The fp FILE parameter (if present) specifies the FILE pointer to read
299       from or write to.
300
301       The PEM read functions all take an argument TYPE **x and return a TYPE
302       * pointer. Where TYPE is whatever structure the function uses. If x is
303       NULL then the parameter is ignored. If x is not NULL but *x is NULL
304       then the structure returned will be written to *x. If neither x nor *x
305       is NULL then an attempt is made to reuse the structure at *x (but see
306       BUGS and EXAMPLES sections).  Irrespective of the value of x a pointer
307       to the structure is always returned (or NULL if an error occurred).
308
309       The PEM functions which write private keys take an enc parameter which
310       specifies the encryption algorithm to use, encryption is done at the
311       PEM level. If this parameter is set to NULL then the private key is
312       written in unencrypted form.
313
314       The cb argument is the callback to use when querying for the pass
315       phrase used for encrypted PEM structures (normally only private keys).
316
317       For the PEM write routines if the kstr parameter is not NULL then klen
318       bytes at kstr are used as the passphrase and cb is ignored.
319
320       If the cb parameters is set to NULL and the u parameter is not NULL
321       then the u parameter is interpreted as a null terminated string to use
322       as the passphrase. If both cb and u are NULL then the default callback
323       routine is used which will typically prompt for the passphrase on the
324       current terminal with echoing turned off.
325
326       The default passphrase callback is sometimes inappropriate (for example
327       in a GUI application) so an alternative can be supplied. The callback
328       routine has the following form:
329
330        int cb(char *buf, int size, int rwflag, void *u);
331
332       buf is the buffer to write the passphrase to. size is the maximum
333       length of the passphrase (i.e. the size of buf). rwflag is a flag which
334       is set to 0 when reading and 1 when writing. A typical routine will ask
335       the user to verify the passphrase (for example by prompting for it
336       twice) if rwflag is 1. The u parameter has the same value as the u
337       parameter passed to the PEM routine. It allows arbitrary data to be
338       passed to the callback by the application (for example a window handle
339       in a GUI application). The callback must return the number of
340       characters in the passphrase or 0 if an error occurred.
341

EXAMPLES

343       Although the PEM routines take several arguments in almost all
344       applications most of them are set to 0 or NULL.
345
346       Read a certificate in PEM format from a BIO:
347
348        X509 *x;
349        x = PEM_read_bio_X509(bp, NULL, 0, NULL);
350        if (x == NULL)
351               {
352               /* Error */
353               }
354
355       Alternative method:
356
357        X509 *x = NULL;
358        if (!PEM_read_bio_X509(bp, &x, 0, NULL))
359               {
360               /* Error */
361               }
362
363       Write a certificate to a BIO:
364
365        if (!PEM_write_bio_X509(bp, x))
366               {
367               /* Error */
368               }
369
370       Write an unencrypted private key to a FILE pointer:
371
372        if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL))
373               {
374               /* Error */
375               }
376
377       Write a private key (using traditional format) to a BIO using triple
378       DES encryption, the pass phrase is prompted for:
379
380        if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
381               {
382               /* Error */
383               }
384
385       Write a private key (using PKCS#8 format) to a BIO using triple DES
386       encryption, using the pass phrase "hello":
387
388        if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello"))
389               {
390               /* Error */
391               }
392
393       Read a private key from a BIO using the pass phrase "hello":
394
395        key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
396        if (key == NULL)
397               {
398               /* Error */
399               }
400
401       Read a private key from a BIO using a pass phrase callback:
402
403        key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
404        if (key == NULL)
405               {
406               /* Error */
407               }
408
409       Skeleton pass phrase callback:
410
411        int pass_cb(char *buf, int size, int rwflag, void *u);
412               {
413               int len;
414               char *tmp;
415               /* We'd probably do something else if 'rwflag' is 1 */
416               printf("Enter pass phrase for \"%s\"\n", u);
417
418               /* get pass phrase, length 'len' into 'tmp' */
419               tmp = "hello";
420               len = strlen(tmp);
421
422               if (len <= 0) return 0;
423               /* if too long, truncate */
424               if (len > size) len = size;
425               memcpy(buf, tmp, len);
426               return len;
427               }
428

NOTES

430       The old PrivateKey write routines are retained for compatibility.  New
431       applications should write private keys using the
432       PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
433       because they are more secure (they use an iteration count of 2048
434       whereas the traditional routines use a count of 1) unless compatibility
435       with older versions of OpenSSL is important.
436
437       The PrivateKey read routines can be used in all applications because
438       they handle all formats transparently.
439
440       A frequent cause of problems is attempting to use the PEM routines like
441       this:
442
443        X509 *x;
444        PEM_read_bio_X509(bp, &x, 0, NULL);
445
446       this is a bug because an attempt will be made to reuse the data at x
447       which is an uninitialised pointer.
448

PEM ENCRYPTION FORMAT

450       This old PrivateKey routines use a non standard technique for
451       encryption.
452
453       The private key (or other data) takes the following form:
454
455        -----BEGIN RSA PRIVATE KEY-----
456        Proc-Type: 4,ENCRYPTED
457        DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
458
459        ...base64 encoded data...
460        -----END RSA PRIVATE KEY-----
461
462       The line beginning DEK-Info contains two comma separated pieces of
463       information: the encryption algorithm name as used by
464       EVP_get_cipherbyname() and an 8 byte salt encoded as a set of
465       hexadecimal digits.
466
467       After this is the base64 encoded encrypted data.
468
469       The encryption key is determined using EVP_BytesToKey(), using salt and
470       an iteration count of 1. The IV used is the value of salt and *not* the
471       IV returned by EVP_BytesToKey().
472

BUGS

474       The PEM read routines in some versions of OpenSSL will not correctly
475       reuse an existing structure. Therefore the following:
476
477        PEM_read_bio_X509(bp, &x, 0, NULL);
478
479       where x already contains a valid certificate, may not work, whereas:
480
481        X509_free(x);
482        x = PEM_read_bio_X509(bp, NULL, 0, NULL);
483
484       is guaranteed to work.
485

RETURN CODES

487       The read routines return either a pointer to the structure read or NULL
488       if an error occurred.
489
490       The write routines return 1 for success or 0 for failure.
491