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