Update docs.
diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod
index e830a19..228e1f9 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 @@
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 @@
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 @@
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 @@
(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.
-It should be called after all operations using a cipher are complete
-so sensitive information does not remain in memory.
+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_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 @@
=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 @@
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 @@
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 @@
/* 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 @@
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 @@
}
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 7f9265d..32e9d54 100644
--- a/doc/crypto/EVP_SignInit.pod
+++ b/doc/crypto/EVP_SignInit.pod
@@ -8,10 +8,12 @@
#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 @@
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 @@
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 @@
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 @@
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 736a0f4..80c656f 100644
--- a/doc/crypto/EVP_VerifyInit.pod
+++ b/doc/crypto/EVP_VerifyInit.pod
@@ -8,30 +8,35 @@
#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 @@
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 @@
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
