Update docs.

3 files changed, 142 insertions, 78 deletions

diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod
index e830a191cc..228e1f9e7e 100644
--- a/doc/crypto/EVP_EncryptInit.pod
+++ b/doc/crypto/EVP_EncryptInit.pod
@@ -2,40 +2,61 @@
 
 =head1 NAME
 
-EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal, EVP_DecryptInit,
-EVP_DecryptUpdate, EVP_DecryptFinal, EVP_CipherInit, EVP_CipherUpdate,
-EVP_CipherFinal, EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl,
-EVP_CIPHER_CTX_cleanup, EVP_get_cipherbyname, EVP_get_cipherbynid,
-EVP_get_cipherbyobj, EVP_CIPHER_nid, EVP_CIPHER_block_size,
-EVP_CIPHER_key_length, EVP_CIPHER_iv_length, EVP_CIPHER_flags,
-EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, EVP_CIPHER_CTX_nid,
-EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, EVP_CIPHER_CTX_iv_length,
-EVP_CIPHER_CTX_get_app_data, EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type,
-EVP_CIPHER_CTX_flags, EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1,
-EVP_CIPHER_asn1_to_param, EVP_CIPHER_CTX_set_padding - EVP cipher routines
+EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate,
+EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate,
+EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate,
+EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length,
+EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit,
+EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal,
+EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname,
+EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid,
+EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length,
+EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher,
+EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length,
+EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data,
+EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags,
+EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param,
+EVP_CIPHER_CTX_set_padding - EVP cipher routines
 
 =head1 SYNOPSIS
 
  #include <openssl/evp.h>
 
- int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
-         unsigned char *key, unsigned char *iv);
+ int EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a);
+
+ int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+	 ENGINE *impl, unsigned char *key, unsigned char *iv);
  int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
          int *outl, unsigned char *in, int inl);
+ int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out,
+         int *outl);
+
+ int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+	 ENGINE *impl, unsigned char *key, unsigned char *iv);
+ int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+         int *outl, unsigned char *in, int inl);
+ int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
+         int *outl);
+
+ int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+         ENGINE *impl, unsigned char *key, unsigned char *iv, int enc);
+ int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+         int *outl, unsigned char *in, int inl);
+ int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
+         int *outl);
+
+ int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+         unsigned char *key, unsigned char *iv);
  int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
          int *outl);
 
  int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
          unsigned char *key, unsigned char *iv);
- int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
-         int *outl, unsigned char *in, int inl);
  int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
          int *outl);
 
  int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
          unsigned char *key, unsigned char *iv, int enc);
- int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
-         int *outl, unsigned char *in, int inl);
  int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
          int *outl);
 
@@ -75,14 +96,19 @@ EVP_CIPHER_asn1_to_param, EVP_CIPHER_CTX_set_padding - EVP cipher routines
 The EVP cipher routines are a high level interface to certain
 symmetric ciphers.
 
-EVP_EncryptInit() initializes a cipher context B<ctx> for encryption
-with cipher B<type>. B<type> is normally supplied by a function such
-as EVP_des_cbc() . B<key> is the symmetric key to use and B<iv> is the
-IV to use (if necessary), the actual number of bytes used for the
-key and IV depends on the cipher. It is possible to set all parameters
-to NULL except B<type> in an initial call and supply the remaining
-parameters in subsequent calls, all of which have B<type> set to NULL.
-This is done when the default cipher parameters are not appropriate.
+EVP_CIPHER_CTX_init() initializes cipher contex B<ctx>.
+
+EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
+with cipher B<type> from ENGINE B<impl>. B<ctx> must be initialized
+before calling this function. B<type> is normally supplied
+by a function such as EVP_des_cbc(). If B<impl> is NULL then the
+default implementation is used. B<key> is the symmetric key to use
+and B<iv> is the IV to use (if necessary), the actual number of bytes
+used for the key and IV depends on the cipher. It is possible to set
+all parameters to NULL except B<type> in an initial call and supply
+the remaining parameters in subsequent calls, all of which have B<type>
+set to NULL. This is done when the default cipher parameters are not
+appropriate.
 
 EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and
 writes the encrypted version to B<out>. This function can be called
@@ -92,7 +118,7 @@ as a result the amount of data written may be anything from zero bytes
 to (inl + cipher_block_size - 1) so B<outl> should contain sufficient
 room. The actual number of bytes written is placed in B<outl>.
 
-If padding is enabled (the default) then EVP_EncryptFinal() encrypts
+If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts
 the "final" data, that is any data that remains in a partial block.
 It uses L<standard block padding|/NOTES> (aka PKCS padding). The encrypted
 final data is written to B<out> which should have sufficient space for
@@ -100,11 +126,11 @@ one cipher block. The number of bytes written is placed in B<outl>. After
 this function is called the encryption operation is finished and no further
 calls to EVP_EncryptUpdate() should be made.
 
-If padding is disabled then EVP_EncryptFinal() will not encrypt any more
+If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more
 data and it will return an error if any data remains in a partial block:
 that is if the total data length is not a multiple of the block size. 
 
-EVP_DecryptInit(), EVP_DecryptUpdate() and EVP_DecryptFinal() are the
+EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the
 corresponding decryption operations. EVP_DecryptFinal() will return an
 error code if padding is enabled and the final block is not correctly
 formatted. The parameters and restrictions are identical to the encryption
@@ -113,15 +139,26 @@ passed to EVP_DecryptUpdate() should have sufficient room for
 (B<inl> + cipher_block_size) bytes unless the cipher block size is 1 in
 which case B<inl> bytes is sufficient.
 
-EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal() are functions
-that can be used for decryption or encryption. The operation performed
-depends on the value of the B<enc> parameter. It should be set to 1 for
-encryption, 0 for decryption and -1 to leave the value unchanged (the
-actual value of 'enc' being supplied in a previous call).
+EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are
+functions that can be used for decryption or encryption. The operation
+performed depends on the value of the B<enc> parameter. It should be set
+to 1 for encryption, 0 for decryption and -1 to leave the value unchanged
+(the actual value of 'enc' being supplied in a previous call).
+
+EVP_CIPHER_CTX_cleanup() clears all information from a cipher context
+and free up any allocated memory associate with it. It should be called
+after all operations using a cipher are complete so sensitive information
+does not remain in memory.
+
+EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
+similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and
+EVP_CipherInit_ex() except the B<ctx> paramter does not need to be
+initialized and they always use the default cipher implementation.
 
-EVP_CIPHER_CTX_cleanup() clears all information from a cipher context.
-It should be called after all operations using a cipher are complete
-so sensitive information does not remain in memory.
+EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() behave in a
+similar way to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and
+EVP_CipherFinal_ex() except B<ctx> is automatically cleaned up 
+after the call.
 
 EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
 return an EVP_CIPHER structure when passed a cipher name, a NID or an
@@ -199,14 +236,14 @@ RC5 can be set.
 
 =head1 RETURN VALUES
 
-EVP_EncryptInit(), EVP_EncryptUpdate() and EVP_EncryptFinal() return 1 for success
-and 0 for failure.
+EVP_CIPHER_CTX_init, EVP_EncryptInit_ex(), EVP_EncryptUpdate() and
+EVP_EncryptFinal_ex() return 1 for success and 0 for failure.
 
-EVP_DecryptInit() and EVP_DecryptUpdate() return 1 for success and 0 for failure.
-EVP_DecryptFinal() returns 0 if the decrypt failed or 1 for success.
+EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for failure.
+EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success.
 
-EVP_CipherInit() and EVP_CipherUpdate() return 1 for success and 0 for failure.
-EVP_CipherFinal() returns 1 for a decryption failure or 1 for success.
+EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure.
+EVP_CipherFinal_ex() returns 1 for a decryption failure or 1 for success.
 
 EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure.
 
@@ -325,12 +362,12 @@ the input data earlier on will not produce a final decrypt error.
 If padding is disabled then the decryption operation will always succeed if
 the total amount of data decrypted is a multiple of the block size.
 
-The functions EVP_EncryptInit(), EVP_EncryptUpdate(), EVP_EncryptFinal(),
-EVP_DecryptInit(), EVP_DecryptUpdate(), EVP_CipherInit() and EVP_CipherUpdate()
-and EVP_CIPHER_CTX_cleanup() did not return errors in OpenSSL version 0.9.5a or
-earlier. Software only versions of encryption algorithms will never return
-error codes for these functions, unless there is a programming error (for example
-and attempt to set the key before the cipher is set in EVP_EncryptInit() ).
+The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(),
+EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for
+compatibility with existing code. New code should use EVP_EncryptInit_ex(),
+EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(),
+EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an
+existing context without allocating and freeing it up on each call.
 
 =head1 BUGS
 
@@ -381,7 +418,8 @@ Encrypt a string using blowfish:
 	char intext[] = "Some Crypto Text";
 	EVP_CIPHER_CTX ctx;
 	FILE *out;
-	EVP_EncryptInit(&ctx, EVP_bf_cbc(), key, iv);
+	EVP_CIPHER_CTX_init(&ctx);
+	EVP_EncryptInit_ex(&ctx, NULL, EVP_bf_cbc(), key, iv);
 
 	if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext)))
 		{
@@ -391,7 +429,7 @@ Encrypt a string using blowfish:
 	/* Buffer passed to EVP_EncryptFinal() must be after data just
 	 * encrypted to avoid overwriting it.
 	 */
-	if(!EVP_EncryptFinal(&ctx, outbuf + outlen, &tmplen))
+	if(!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen))
 		{
 		/* Error */
 		return 0;
@@ -428,10 +466,11 @@ General encryption, decryption function example using FILE I/O and RC2 with an
 	unsigned char key[] = "0123456789";
 	unsigned char iv[] = "12345678";
 	/* Don't set key or IV because we will modify the parameters */
-	EVP_CipherInit(&ctx, EVP_rc2(), NULL, NULL, do_encrypt);
+	EVP_CIPHER_CTX_init(&ctx);
+	EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt);
 	EVP_CIPHER_CTX_set_key_length(&ctx, 10);
 	/* We finished modifying parameters so now we can set key and IV */
-	EVP_CipherInit(&ctx, NULL, key, iv, do_encrypt);
+	EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
 
 	for(;;) 
 		{
@@ -444,7 +483,7 @@ General encryption, decryption function example using FILE I/O and RC2 with an
 			}
 		fwrite(outbuf, 1, outlen, out);
 		}
-	if(!EVP_CipherFinal(&ctx, outbuf, &outlen))
+	if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen))
 		{
 		/* Error */
 		return 0;
diff --git a/doc/crypto/EVP_SignInit.pod b/doc/crypto/EVP_SignInit.pod
index 7f9265d0a6..32e9d54809 100644
--- a/doc/crypto/EVP_SignInit.pod
+++ b/doc/crypto/EVP_SignInit.pod
@@ -8,10 +8,12 @@ EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions
 
  #include <openssl/evp.h>
 
- void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
- void EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
+ int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
+ int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
  int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey);
 
+ void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
+
  int EVP_PKEY_size(EVP_PKEY *pkey);
 
 =head1 DESCRIPTION
@@ -19,9 +21,9 @@ EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions
 The EVP signature routines are a high level interface to digital
 signatures.
 
-EVP_SignInit() initializes a signing context B<ctx> to using digest
-B<type>: this will typically be supplied by a function such as
-EVP_sha1().
+EVP_SignInit_ex() sets up signing context B<ctx> to use digest
+B<type> from ENGINE B<impl>. B<ctx> must be initialized with
+EVP_MD_CTX_init() before calling this function.
 
 EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the
 signature context B<ctx>. This function can be called several times on the
@@ -31,18 +33,18 @@ EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey>
 and places the signature in B<sig>. If the B<s> parameter is not NULL
 then the number of bytes of data written (i.e. the length of the signature)
 will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes
-will be written.  After calling EVP_SignFinal() no additional calls to
-EVP_SignUpdate() can be made, but EVP_SignInit() can be called to initialize
-a new signature operation.
+will be written. 
+
+EVP_SignInit() initializes a signing context B<ctx> to use the default
+implementation of digest B<type>.
 
 EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual
 signature returned by EVP_SignFinal() may be smaller.
 
 =head1 RETURN VALUES
 
-EVP_SignInit() and EVP_SignUpdate() do not return values.
-
-EVP_SignFinal() returns 1 for success and 0 for failure.
+EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1
+for success and 0 for failure.
 
 EVP_PKEY_size() returns the maximum size of a signature in bytes.
 
@@ -63,11 +65,18 @@ When signing with DSA private keys the random number generator must be seeded
 or the operation will fail. The random number generator does not need to be
 seeded for RSA signatures.
 
+The call to EVP_SignFinal() internally finalizes a copy of the digest context.
+This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called
+later to digest and sign additional data.
+
+Since only a copy of the digest context is ever finalized the context must
+be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
+will occur.
+
 =head1 BUGS
 
-Several of the functions do not return values: maybe they should. Although the
-internal digest operations will never fail some future hardware based operations
-might.
+Older versions of this documentation wrongly stated that calls to 
+EVP_SignUpdate() could not be made after calling EVP_SignFinal().
 
 =head1 SEE ALSO
 
@@ -82,4 +91,6 @@ L<sha(3)|sha(3)>, L<digest(1)|digest(1)>
 EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are
 available in all versions of SSLeay and OpenSSL.
 
+EVP_SignInit_ex() was added in OpenSSL 0.9.7
+
 =cut
diff --git a/doc/crypto/EVP_VerifyInit.pod b/doc/crypto/EVP_VerifyInit.pod
index 736a0f4a82..80c656fde8 100644
--- a/doc/crypto/EVP_VerifyInit.pod
+++ b/doc/crypto/EVP_VerifyInit.pod
@@ -8,30 +8,35 @@ EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification f
 
  #include <openssl/evp.h>
 
- void EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type);
- void EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
+ int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
+ int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
  int EVP_VerifyFinal(EVP_MD_CTX *ctx,unsigned char *sigbuf, unsigned int siglen,EVP_PKEY *pkey);
 
+ int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type);
+
 =head1 DESCRIPTION
 
 The EVP signature verification routines are a high level interface to digital
 signatures.
 
-EVP_VerifyInit() initializes a verification context B<ctx> to using digest
-B<type>: this will typically be supplied by a function such as EVP_sha1().
+EVP_VerifyInit_ex() sets up verification context B<ctx> to use digest
+B<type> from ENGINE B<impl>. B<ctx> must be initialized by calling
+EVP_MD_CTX_init() before calling this function.
 
 EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
 verification context B<ctx>. This function can be called several times on the
 same B<ctx> to include additional data.
 
 EVP_VerifyFinal() verifies the data in B<ctx> using the public key B<pkey>
-and against the B<siglen> bytes at B<sigbuf>. After calling EVP_VerifyFinal()
-no additional calls to EVP_VerifyUpdate() can be made, but EVP_VerifyInit()
-can be called to initialize a new verification operation.
+and against the B<siglen> bytes at B<sigbuf>.
+
+EVP_VerifyInit() initializes verification context B<ctx> to use the default
+implementation of digest B<type>.
 
 =head1 RETURN VALUES
 
-EVP_VerifyInit() and EVP_VerifyUpdate() do not return values.
+EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for
+failure.
 
 EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if some
 other error occurred.
@@ -49,11 +54,18 @@ digest algorithm must be used with the correct public key type. A list of
 algorithms and associated public key algorithms appears in 
 L<EVP_DigestInit(3)|EVP_DigestInit(3)>.
 
+The call to EVP_VerifyFinal() internally finalizes a copy of the digest context.
+This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can be called
+later to digest and verify additional data.
+
+Since only a copy of the digest context is ever finalized the context must
+be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
+will occur.
+
 =head1 BUGS
 
-Several of the functions do not return values: maybe they should. Although the
-internal digest operations will never fail some future hardware based operations
-might.
+Older versions of this documentation wrongly stated that calls to 
+EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal().
 
 =head1 SEE ALSO
 
@@ -69,4 +81,6 @@ L<sha(3)|sha(3)>, L<digest(1)|digest(1)>
 EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are
 available in all versions of SSLeay and OpenSSL.
 
+EVP_VerifyInit_ex() was added in OpenSSL 0.9.7
+
 =cut