Add certificate callback. If set this is called whenever a certificate

[openssl.git] / doc / crypto / pem.pod

diff --git a/doc/crypto/pem.pod b/doc/crypto/pem.pod
index ce8f374252bbd3038924b0dc6c89134beafd1bfe..d5b189611956e81780e9961126338bbc36260439 100644 (file)
--- a/doc/crypto/pem.pod
+++ b/doc/crypto/pem.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-PEM - PEM routines
+PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE, PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines
 
 =head1 SYNOPSIS
 
@@ -330,7 +330,7 @@ most of them are set to 0 or NULL.
 Read a certificate in PEM format from a BIO:
 
  X509 *x;
- x = PEM_read_bio(bp, NULL, 0, NULL);
+ x = PEM_read_bio_X509(bp, NULL, 0, NULL);
  if (x == NULL)
        {
        /* Error */
@@ -409,7 +409,7 @@ Skeleton pass phrase callback:
        memcpy(buf, tmp, len);
        return len;
        }
-       
+
 =head1 NOTES
 
 The old B<PrivateKey> write routines are retained for compatibility.
@@ -431,23 +431,46 @@ this:
 this is a bug because an attempt will be made to reuse the data at B<x>
 which is an uninitialised pointer.
 
+=head1 PEM ENCRYPTION FORMAT
+
+This old B<PrivateKey> routines use a non standard technique for encryption.
+
+The private key (or other data) takes the following form: 
+
+ -----BEGIN RSA PRIVATE KEY-----
+ Proc-Type: 4,ENCRYPTED
+ DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
+
+ ...base64 encoded data...
+ -----END RSA PRIVATE KEY-----
+
+The line beginning DEK-Info contains two comma separated pieces of information:
+the encryption algorithm name as used by EVP_get_cipherbyname() and an 8
+byte B<salt> encoded as a set of hexadecimal digits.
+
+After this is the base64 encoded encrypted data.
+
+The encryption key is determined using EVP_bytestokey(), using B<salt> and an
+iteration count of 1. The IV used is the value of B<salt> and *not* the IV
+returned by EVP_bytestokey().
+
 =head1 BUGS
 
 The PEM read routines in some versions of OpenSSL will not correctly reuse
 an existing structure. Therefore the following:
 
- PEM_read_bio(bp, &x, 0, NULL);
+ PEM_read_bio_X509(bp, &x, 0, NULL);
 
 where B<x> already contains a valid certificate, may not work, whereas: 
 
  X509_free(x);
- x = PEM_read_bio(bp, NULL, 0, NULL);
+ x = PEM_read_bio_X509(bp, NULL, 0, NULL);
 
 is guaranteed to work.
 
 =head1 RETURN CODES
 
 The read routines return either a pointer to the structure read or NULL
-is an error occurred.
+if an error occurred.
 
 The write routines return 1 for success or 0 for failure.