crypto/openssl-0.9.7d/doc/crypto/pem.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 PEM - 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
 183 The PEM functions read or write structures in PEM format. In
 184 this sense PEM format is simply base64 encoded data surrounded
 185 by header lines.
 186
 187 For more details about the meaning of arguments see the
 188 B<PEM FUNCTION ARGUMENTS> section.
 189
 190 Each operation has four functions associated with it. For
 191 clarity the term "B<foobar> functions" will be used to collectively
 192 refer to the PEM_read_bio_foobar(), PEM_read_foobar(),
 193 PEM_write_bio_foobar() and PEM_write_foobar() functions.
 194
 195 The B<PrivateKey> functions read or write a private key in
 196 PEM format using an EVP_PKEY structure. The write routines use
 197 "traditional" private key format and can handle both RSA and DSA
 198 private keys. The read functions can additionally transparently
 199 handle PKCS#8 format encrypted and unencrypted keys too.
 200
 201 PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey()
 202 write a private key in an EVP_PKEY structure in PKCS#8
 203 EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption
 204 algorithms. The B<cipher> argument specifies the encryption algoritm to
 205 use: unlike all other PEM routines the encryption is applied at the
 206 PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no
 207 encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead.
 208
 209 PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
 210 also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
 211 it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
 212 to use is specified in the B<nid> parameter and should be the NID of the
 213 corresponding OBJECT IDENTIFIER (see NOTES section).
 214
 215 The B<PUBKEY> functions process a public key using an EVP_PKEY
 216 structure. The public key is encoded as a SubjectPublicKeyInfo
 217 structure.
 218
 219 The B<RSAPrivateKey> functions process an RSA private key using an
 220 RSA structure. It handles the same formats as the B<PrivateKey>
 221 functions but an error occurs if the private key is not RSA.
 222
 223 The B<RSAPublicKey> functions process an RSA public key using an
 224 RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey
 225 structure.
 226
 227 The B<RSA_PUBKEY> functions also process an RSA public key using
 228 an RSA structure. However the public key is encoded using a
 229 SubjectPublicKeyInfo structure and an error occurs if the public
 230 key is not RSA.
 231
 232 The B<DSAPrivateKey> functions process a DSA private key using a
 233 DSA structure. It handles the same formats as the B<PrivateKey>
 234 functions but an error occurs if the private key is not DSA.
 235
 236 The B<DSA_PUBKEY> functions process a DSA public key using
 237 a DSA structure. The public key is encoded using a
 238 SubjectPublicKeyInfo structure and an error occurs if the public
 239 key is not DSA.
 240
 241 The B<DSAparams> functions process DSA parameters using a DSA
 242 structure. The parameters are encoded using a foobar structure.
 243
 244 The B<DHparams> functions process DH parameters using a DH
 245 structure. The parameters are encoded using a PKCS#3 DHparameter
 246 structure.
 247
 248 The B<X509> functions process an X509 certificate using an X509
 249 structure. They will also process a trusted X509 certificate but
 250 any trust settings are discarded.
 251
 252 The B<X509_AUX> functions process a trusted X509 certificate using
 253 an X509 structure.
 254
 255 The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10
 256 certificate request using an X509_REQ structure. The B<X509_REQ>
 257 write functions use B<CERTIFICATE REQUEST> in the header whereas
 258 the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST>
 259 (as required by some CAs). The B<X509_REQ> read functions will
 260 handle either form so there are no B<X509_REQ_NEW> read functions.
 261
 262 The B<X509_CRL> functions process an X509 CRL using an X509_CRL
 263 structure.
 264
 265 The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7
 266 structure.
 267
 268 The B<NETSCAPE_CERT_SEQUENCE> functions process a Netscape Certificate
 269 Sequence using a NETSCAPE_CERT_SEQUENCE structure.
 270
 271 =head1 PEM FUNCTION ARGUMENTS
 272
 273 The PEM functions have many common arguments.
 274
 275 The B<bp> BIO parameter (if present) specifies the BIO to read from
 276 or write to.
 277
 278 The B<fp> FILE parameter (if present) specifies the FILE pointer to
 279 read from or write to.
 280
 281 The PEM read functions all take an argument B<TYPE **x> and return
 282 a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function
 283 uses. If B<x> is NULL then the parameter is ignored. If B<x> is not
 284 NULL but B<*x> is NULL then the structure returned will be written
 285 to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made
 286 to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections).
 287 Irrespective of the value of B<x> a pointer to the structure is always
 288 returned (or NULL if an error occurred).
 289
 290 The PEM functions which write private keys take an B<enc> parameter
 291 which specifies the encryption algorithm to use, encryption is done
 292 at the PEM level. If this parameter is set to NULL then the private
 293 key is written in unencrypted form.
 294
 295 The B<cb> argument is the callback to use when querying for the pass
 296 phrase used for encrypted PEM structures (normally only private keys).
 297
 298 For the PEM write routines if the B<kstr> parameter is not NULL then
 299 B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is
 300 ignored.
 301
 302 If the B<cb> parameters is set to NULL and the B<u> parameter is not
 303 NULL then the B<u> parameter is interpreted as a null terminated string
 304 to use as the passphrase. If both B<cb> and B<u> are NULL then the
 305 default callback routine is used which will typically prompt for the
 306 passphrase on the current terminal with echoing turned off.
 307
 308 The default passphrase callback is sometimes inappropriate (for example
 309 in a GUI application) so an alternative can be supplied. The callback
 310 routine has the following form:
 311
 312  int cb(char *buf, int size, int rwflag, void *u);
 313
 314 B<buf> is the buffer to write the passphrase to. B<size> is the maximum
 315 length of the passphrase (i.e. the size of buf). B<rwflag> is a flag
 316 which is set to 0 when reading and 1 when writing. A typical routine
 317 will ask the user to verify the passphrase (for example by prompting
 318 for it twice) if B<rwflag> is 1. The B<u> parameter has the same
 319 value as the B<u> parameter passed to the PEM routine. It allows
 320 arbitrary data to be passed to the callback by the application
 321 (for example a window handle in a GUI application). The callback
 322 B<must> return the number of characters in the passphrase or 0 if
 323 an error occurred.
 324
 325 =head1 EXAMPLES
 326
 327 Although the PEM routines take several arguments in almost all applications
 328 most of them are set to 0 or NULL.
 329
 330 Read 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
 339 Alternative method:
 340
 341  X509 *x = NULL;
 342  if (!PEM_read_bio_X509(bp, &x, 0, NULL))
 343         {
 344         /* Error */
 345         }
 346
 347 Write a certificate to a BIO:
 348
 349  if (!PEM_write_bio_X509(bp, x))
 350         {
 351         /* Error */
 352         }
 353
 354 Write 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
 361 Write a private key (using traditional format) to a BIO using
 362 triple 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
 369 Write a private key (using PKCS#8 format) to a BIO using triple
 370 DES 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
 377 Read 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
 385 Read 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
 393 Skeleton 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
 415 The old B<PrivateKey> write routines are retained for compatibility.
 416 New applications should write private keys using the
 417 PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
 418 because they are more secure (they use an iteration count of 2048 whereas
 419 the traditional routines use a count of 1) unless compatibility with older
 420 versions of OpenSSL is important.
 421
 422 The B<PrivateKey> read routines can be used in all applications because
 423 they handle all formats transparently.
 424
 425 A frequent cause of problems is attempting to use the PEM routines like
 426 this:
 427
 428  X509 *x;
 429  PEM_read_bio_X509(bp, &x, 0, NULL);
 430
 431 this is a bug because an attempt will be made to reuse the data at B<x>
 432 which is an uninitialised pointer.
 433
 434 =head1 PEM ENCRYPTION FORMAT
 435
 436 This old B<PrivateKey> routines use a non standard technique for encryption.
 437
 438 The 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
 447 The line beginning DEK-Info contains two comma separated pieces of information:
 448 the encryption algorithm name as used by EVP_get_cipherbyname() and an 8
 449 byte B<salt> encoded as a set of hexadecimal digits.
 450
 451 After this is the base64 encoded encrypted data.
 452
 453 The encryption key is determined using EVP_bytestokey(), using B<salt> and an
 454 iteration count of 1. The IV used is the value of B<salt> and *not* the IV
 455 returned by EVP_bytestokey().
 456
 457 =head1 BUGS
 458
 459 The PEM read routines in some versions of OpenSSL will not correctly reuse
 460 an existing structure. Therefore the following:
 461
 462  PEM_read_bio_X509(bp, &x, 0, NULL);
 463
 464 where 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
 469 is guaranteed to work.
 470
 471 =head1 RETURN CODES
 472
 473 The read routines return either a pointer to the structure read or NULL
 474 is an error occurred.
 475
 476 The write routines return 1 for success or 0 for failure.