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 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
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 foobar structure.
265
266       The DHparams functions process DH parameters using a DH structure. The
267       parameters are encoded using a PKCS#3 DHparameter structure.
268
269       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
273       The X509_AUX functions process a trusted X509 certificate using an X509
274       structure.
275
276       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
283       The X509_CRL functions process an X509 CRL using an X509_CRL structure.
284
285       The PKCS7 functions process a PKCS#7 ContentInfo using a PKCS7
286       structure.
287
288       The NETSCAPE_CERT_SEQUENCE functions process a Netscape Certificate
289       Sequence using a NETSCAPE_CERT_SEQUENCE structure.
290

PEM FUNCTION ARGUMENTS

292       The PEM functions have many common arguments.
293
294       The bp BIO parameter (if present) specifies the BIO to read from or
295       write to.
296
297       The fp FILE parameter (if present) specifies the FILE pointer to read
298       from or write to.
299
300       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
308       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
313       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
316       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
319       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
325       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
329        int cb(char *buf, int size, int rwflag, void *u);
330
331       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

EXAMPLES

342       Although the PEM routines take several arguments in almost all
343       applications most of them are set to 0 or NULL.
344
345       Read a certificate in PEM format from a BIO:
346
347        X509 *x;
348        x = PEM_read_bio_X509(bp, NULL, 0, NULL);
349        if (x == NULL)
350               {
351               /* Error */
352               }
353
354       Alternative method:
355
356        X509 *x = NULL;
357        if (!PEM_read_bio_X509(bp, &x, 0, NULL))
358               {
359               /* Error */
360               }
361
362       Write a certificate to a BIO:
363
364        if (!PEM_write_bio_X509(bp, x))
365               {
366               /* Error */
367               }
368
369       Write an unencrypted private key to a FILE pointer:
370
371        if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL))
372               {
373               /* Error */
374               }
375
376       Write a private key (using traditional format) to a BIO using triple
377       DES encryption, the pass phrase is prompted for:
378
379        if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
380               {
381               /* Error */
382               }
383
384       Write a private key (using PKCS#8 format) to a BIO using triple DES
385       encryption, using the pass phrase "hello":
386
387        if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello"))
388               {
389               /* Error */
390               }
391
392       Read a private key from a BIO using the pass phrase "hello":
393
394        key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
395        if (key == NULL)
396               {
397               /* Error */
398               }
399
400       Read a private key from a BIO using a pass phrase callback:
401
402        key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
403        if (key == NULL)
404               {
405               /* Error */
406               }
407
408       Skeleton pass phrase callback:
409
410        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
417               /* get pass phrase, length 'len' into 'tmp' */
418               tmp = "hello";
419               len = strlen(tmp);
420
421               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

NOTES

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
436       The PrivateKey read routines can be used in all applications because
437       they handle all formats transparently.
438
439       A frequent cause of problems is attempting to use the PEM routines like
440       this:
441
442        X509 *x;
443        PEM_read_bio_X509(bp, &x, 0, NULL);
444
445       this is a bug because an attempt will be made to reuse the data at x
446       which is an uninitialised pointer.
447

PEM ENCRYPTION FORMAT

449       This old PrivateKey routines use a non standard technique for
450       encryption.
451
452       The private key (or other data) takes the following form:
453
454        -----BEGIN RSA PRIVATE KEY-----
455        Proc-Type: 4,ENCRYPTED
456        DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
457
458        ...base64 encoded data...
459        -----END RSA PRIVATE KEY-----
460
461       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
466       After this is the base64 encoded encrypted data.
467
468       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

BUGS

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

RETURN CODES

486       The read routines return either a pointer to the structure read or NULL
487       if an error occurred.
488
489       The write routines return 1 for success or 0 for failure.
490
491
492
4931.0.0e                            2009-06-02                            pem(3)
Impressum