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