Update docs.

2 files changed, 81 insertions, 7 deletions

diff --git a/doc/crypto/EVP_DigestInit.pod b/doc/crypto/EVP_DigestInit.pod
index 2ab27c360c..9b62059063 100644
--- a/doc/crypto/EVP_DigestInit.pod
+++ b/doc/crypto/EVP_DigestInit.pod
@@ -96,7 +96,7 @@ returns is of zero length.
 
 EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
 return an B<EVP_MD> structure when passed a digest name, a digest NID or
-and ASN1_OBJECT structure respectively. The digest table must be initialised
+an ASN1_OBJECT structure respectively. The digest table must be initialised
 using, for example, OpenSSL_add_all_digests() for these functions to work.
 
 =head1 RETURN VALUES
@@ -112,9 +112,9 @@ EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size(e), EVP_MD_size(),
 EVP_MD_CTX_block_size()	and EVP_MD_block_size() return the digest or block
 size in bytes.
 
-EVP_md_null(), EVP_MD *EVP_md2(), EVP_MD *EVP_md5(), EVP_MD *EVP_sha(),
-EVP_sha1(), EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return
-pointers to the corresponding EVP_MD structures.
+EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(),
+EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the
+corresponding EVP_MD structures.
 
 EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
 return either an B<EVP_MD> structure or NULL if an error occurs.
@@ -186,7 +186,7 @@ in code that must be recompiled if the size of B<EVP_MD_CTX> increases.
 
 L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
 L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>,
-L<sha(3)|sha(3)>
+L<sha(3)|sha(3)>, L<digest(1)|digest(1)>
 
 =head1 HISTORY
 
diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod
index 19dca2f612..c84f593dbb 100644
--- a/doc/crypto/EVP_EncryptInit.pod
+++ b/doc/crypto/EVP_EncryptInit.pod
@@ -29,7 +29,7 @@ EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal - EVP cipher routines
  #define EVP_CIPHER_nid(e)		((e)->nid)
  #define EVP_CIPHER_block_size(e)	((e)->block_size)
  #define EVP_CIPHER_key_length(e)	((e)->key_len)
- #define EVP_CIPHER_iv_length(e)		((e)->iv_len)
+ #define EVP_CIPHER_iv_length(e)	((e)->iv_len)
 
  int EVP_CIPHER_type(const EVP_CIPHER *ctx);
  #define EVP_CIPHER_CTX_cipher(e)	((e)->cipher)
@@ -39,6 +39,9 @@ EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal - EVP cipher routines
  #define EVP_CIPHER_CTX_iv_length(e)	((e)->cipher->iv_len)
  #define EVP_CIPHER_CTX_type(c)         EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c))
 
+ int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
+ int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
+
 =head1 DESCRIPTION
 
 The EVP cipher routines are a high level interface to certain
@@ -48,7 +51,12 @@ EVP_EncryptInit() initialises 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.
+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. This is normally done when the 
+EVP_CIPHER_asn1_to_param() function is called to set the cipher
+parameters from an ASN1 AlgorithmIdentifier and the key from a
+different source.
 
 EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and
 writes the encrypted version to B<out>. This function can be called
@@ -82,6 +90,56 @@ 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_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
+return an EVP_CIPHER structure when passed a cipher name, a NID or an
+ASN1_OBJECT structure.
+
+EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when
+passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure.  The actual NID
+value is an internal value which may not have a corresponding OBJECT
+IDENTIFIER.
+
+EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
+length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
+structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length
+for all ciphers.
+
+EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
+length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>.
+It will return zero if the cipher does not use an IV.  The constant
+B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers.
+
+EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
+size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
+structure. The constant B<EVP_MAX_IV_LENGTH> is also the maximum block
+length for all ciphers.
+
+EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed
+cipher or context. This "type" is the actual NID of the cipher OBJECT
+IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and
+128 bit RC2 have the same NID.
+
+EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed
+an B<EVP_CIPHER_CTX> structure.
+
+EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based
+on the passed cipher. This will typically include any parameters and an
+IV. The cipher IV (if any) must be set when this call is made. This call
+should be made before the cipher is actually "used" (before any
+EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function
+may fail if the cipher does not have any ASN1 support.
+
+EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1
+AlgorithmIdentifier "parameter". The precise effect depends on the cipher
+In the case of RC2, for example, it will set the IV and effective key length.
+This function should be called after the base cipher type is set but before
+the key is set. For example EVP_CipherInit() will be called with the IV and
+key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally
+EVP_CipherInit() again with all parameters except the key set to NULL. It is
+possible for this function to fail if the cipher does not have any ASN1 support
+or the parameters cannot be set (for example the RC2 effective key length
+does not have an B<EVP_CIPHER> structure).
+
 =head1 RETURN VALUES
 
 EVP_EncryptInit(), EVP_EncryptUpdate() and EVP_EncryptFinal() do not return
@@ -94,6 +152,22 @@ EVP_CipherInit() and EVP_CipherUpdate() do not return values.
 EVP_CipherFinal() returns 1 for a decryption failure or 1 for success, if
 the operation is encryption then it always returns 1.
 
+EVP_CIPHER_CTX_cleanup() does not return a value.
+
+EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
+return an B<EVP_CIPHER> structure or NULL on error.
+
+EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID.
+
+EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
+size.
+
+EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
+length.
+
+EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
+length or zero if the cipher does not use an IV.
+
 =head1 NOTES
 
 Where possible the B<EVP> interface to symmetric ciphers should be used in