RT1665,2300: Crypto doc cleanups

RT1665: aes documentation.

Paul Green wrote a nice aes.pod file.
But we now encourage the EVP interface.
So I took his RT item and used it as impetus to add
the AES modes to EVP_EncryptInit.pod
I also noticed that rc4.pod has spurious references to some other
cipher pages, so I removed them.

RT2300: Clean up MD history (merged into RT1665)

Put HISTORY section only in EVP_DigestInit.pod. Also add words
to discourage use of older cipher-specific API, and remove SEE ALSO
links that point to them.

Make sure digest pages have a NOTE that says use EVP_DigestInit.

Review feedback:
More cleanup in EVP_EncryptInit.pod
Fixed SEE ALSO links in ripemd160.pod, sha.pod, mdc2.pod, blowfish.pod,
rc4.d, and des.pod.  Re-order sections in des.pod for consistency

Reviewed-by: Matt Caswell <matt@openssl.org>

9 files changed, 83 insertions, 90 deletions

diff --git a/doc/crypto/EVP_DigestInit.pod b/doc/crypto/EVP_DigestInit.pod
index 0895e8c392..d9fada9c0b 100644
--- a/doc/crypto/EVP_DigestInit.pod
+++ b/doc/crypto/EVP_DigestInit.pod
@@ -67,7 +67,8 @@ EVP digest routines
 
 =head1 DESCRIPTION
 
-The EVP digest routines are a high level interface to message digests.
+The EVP digest routines are a high level interface to message digests,
+and should be used instead of the cipher-specific functions.
 
 EVP_MD_CTX_init() initializes digest context B<ctx>.
 
diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod
index 57b3458269..d68d4bca5b 100644
--- a/doc/crypto/EVP_EncryptInit.pod
+++ b/doc/crypto/EVP_EncryptInit.pod
@@ -24,9 +24,12 @@ EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_idea_cbc, EVP_rc2_cbc,
 EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc,
 EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc,
 EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, EVP_rc5_32_12_16_cbc,
-EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb, 
-EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm,
-EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines
+EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb,
+EVP_aes_128_cbc, EVP_aes_128_ecb, EVP_aes_128_cfb, EVP_aes_128_ofb,
+EVP_aes_192_cbc, EVP_aes_192_ecb, EVP_aes_192_cfb, EVP_aes_192_ofb,
+EVP_aes_256_cbc, EVP_aes_256_ecb, EVP_aes_256_cfb, EVP_aes_256_ofb,
+EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm,
+EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines
 
 =head1 SYNOPSIS
 
@@ -138,7 +141,7 @@ calls to EVP_EncryptUpdate() should be made.
 
 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. 
+that is if the total data length is not a multiple of the block size.
 
 EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the
 corresponding decryption operations. EVP_DecryptFinal() will return an
@@ -278,7 +281,7 @@ OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER.
 
 EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure.
 
-EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for 
+EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for
 success or zero for failure.
 
 =head1 CIPHER LISTING
@@ -291,70 +294,83 @@ All algorithms have a fixed key length unless otherwise stated.
 
 Null cipher: does nothing.
 
-=item EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void)
+=item EVP_aes_128_cbc(), EVP_aes_128_ecb(), EVP_aes_128_cfb(), EVP_aes_128_ofb()
 
-DES in CBC, ECB, CFB and OFB modes respectively. 
+AES with a 128-bit key in CBC, ECB, CFB and OFB modes respectively.
 
-=item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void),  EVP_des_ede_cfb(void)
+=item EVP_aes_192_cbc(), EVP_aes_192_ecb(), EVP_aes_192_cfb(), EVP_aes_192_ofb()
+
+AES with a 192-bit key in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_aes_256_cbc(), EVP_aes_256_ecb(), EVP_aes_256_cfb(), EVP_aes_256_ofb()
+
+AES with a 256-bit key in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_des_cbc(), EVP_des_ecb(), EVP_des_cfb(), EVP_des_ofb()
+
+DES in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_des_ede_cbc(), EVP_des_ede(), EVP_des_ede_ofb(),  EVP_des_ede_cfb()
 
 Two key triple DES in CBC, ECB, CFB and OFB modes respectively.
 
-=item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void),  EVP_des_ede3_cfb(void)
+=item EVP_des_ede3_cbc(), EVP_des_ede3(), EVP_des_ede3_ofb(),  EVP_des_ede3_cfb()
 
 Three key triple DES in CBC, ECB, CFB and OFB modes respectively.
 
-=item EVP_desx_cbc(void)
+=item EVP_desx_cbc()
 
 DESX algorithm in CBC mode.
 
-=item EVP_rc4(void)
+=item EVP_rc4()
 
 RC4 stream cipher. This is a variable key length cipher with default key length 128 bits.
 
-=item EVP_rc4_40(void)
+=item EVP_rc4_40()
 
-RC4 stream cipher with 40 bit key length. This is obsolete and new code should use EVP_rc4()
+RC4 stream cipher with 40 bit key length.
+This is obsolete and new code should use EVP_rc4()
 and the EVP_CIPHER_CTX_set_key_length() function.
 
-=item EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void)
+=item EVP_idea_cbc() EVP_idea_ecb(), EVP_idea_cfb(), EVP_idea_ofb(), EVP_idea_cbc()
 
 IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
 
-=item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void)
+=item EVP_rc2_cbc(), EVP_rc2_ecb(), EVP_rc2_cfb(), EVP_rc2_ofb()
 
 RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
 length cipher with an additional parameter called "effective key bits" or "effective key length".
 By default both are set to 128 bits.
 
-=item EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void)
+=item EVP_rc2_40_cbc(), EVP_rc2_64_cbc()
 
 RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits.
 These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and
 EVP_CIPHER_CTX_ctrl() to set the key length and effective key length.
 
-=item EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void);
+=item EVP_bf_cbc(), EVP_bf_ecb(), EVP_bf_cfb(), EVP_bf_ofb()
 
 Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
 length cipher.
 
-=item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void)
+=item EVP_cast5_cbc(), EVP_cast5_ecb(), EVP_cast5_cfb(), EVP_cast5_ofb()
 
 CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
 length cipher.
 
-=item EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void)
+=item EVP_rc5_32_12_16_cbc(), EVP_rc5_32_12_16_ecb(), EVP_rc5_32_12_16_cfb(), EVP_rc5_32_12_16_ofb()
 
 RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length
 cipher with an additional "number of rounds" parameter. By default the key length is set to 128
 bits and 12 rounds.
 
-=item EVP_aes_128_gcm(void), EVP_aes_192_gcm(void), EVP_aes_256_gcm(void)
+=item EVP_aes_128_gcm(), EVP_aes_192_gcm(), EVP_aes_256_gcm()
 
 AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively.
 These ciphers require additional control operations to function correctly: see
 L<GCM mode> section below for details.
 
-=item EVP_aes_128_ccm(void), EVP_aes_192_ccm(void), EVP_aes_256_ccm(void)
+=item EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm()
 
 AES Counter with CBC-MAC Mode (CCM) for 128, 192 and 256 bit keys respectively.
 These ciphers require additional control operations to function correctly: see
@@ -368,7 +384,7 @@ For GCM mode ciphers the behaviour of the EVP interface is subtly altered and
 several GCM specific ctrl operations are supported.
 
 To specify any additional authenticated data (AAD) a call to EVP_CipherUpdate(),
-EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output 
+EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output
 parameter B<out> set to B<NULL>.
 
 When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal()
@@ -382,7 +398,7 @@ The following ctrls are supported in GCM mode:
 
 Sets the GCM IV length: this call can only be made before specifying an IV. If
 not called a default IV length is used (96 bits for AES).
- 
+
  EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, taglen, tag);
 
 Writes B<taglen> bytes of the tag value to the buffer indicated by B<tag>.
@@ -393,7 +409,7 @@ processed (e.g. after an EVP_EncryptFinal() call).
 
 Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal
 when decrypting data and must be made B<before> any data is processed (e.g.
-before any EVP_DecryptUpdate() call). 
+before any EVP_DecryptUpdate() call).
 
 See L<EXAMPLES> below for an example of the use of GCM mode.
 
@@ -403,14 +419,14 @@ The behaviour of CCM mode ciphers is similar to CCM mode but with a few
 additional requirements and different ctrl values.
 
 Like GCM mode any additional authenticated data (AAD) is passed by calling
-EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output 
+EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output
 parameter B<out> set to B<NULL>. Additionally the total plaintext or ciphertext
 length B<MUST> be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or
-EVP_DecryptUpdate() with the output and input parameters (B<in> and B<out>) 
+EVP_DecryptUpdate() with the output and input parameters (B<in> and B<out>)
 set to B<NULL> and the length passed in the B<inl> parameter.
 
 The following ctrls are supported in CCM mode:
- 
+
  EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, taglen, tag);
 
 This call is made to set the expected B<CCM> tag value when decrypting or
@@ -439,7 +455,7 @@ B<EVP> interface will ensure the use of platform specific cryptographic
 acceleration such as AES-NI (the low level interfaces do not provide the
 guarantee).
 
-PKCS padding works by adding B<n> padding bytes of value B<n> to make the total 
+PKCS padding works by adding B<n> padding bytes of value B<n> to make the total
 length of the encrypted data a multiple of the block size. Padding is always
 added so if the data is already a multiple of the block size B<n> will equal
 the block size. For example if the block size is 8 and 11 bytes are to be
@@ -469,7 +485,7 @@ a limitation of the current RC5 code rather than the EVP interface.
 
 EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with
 default key lengths. If custom ciphers exceed these values the results are
-unpredictable. This is because it has become standard practice to define a 
+unpredictable. This is because it has become standard practice to define a
 generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes.
 
 The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested
@@ -523,7 +539,7 @@ Encrypt a string using IDEA:
 
 The ciphertext from the above example can be decrypted using the B<openssl>
 utility with the command line (shown on two lines for clarity):
- 
+
  openssl idea -d <filename
           -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708
 
@@ -552,7 +568,7 @@ with a 128-bit key:
 	/* Now we can set key and IV */
 	EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
 
-	for(;;) 
+	for(;;)
 		{
 		inlen = fread(inbuf, 1, 1024, in);
 		if(inlen <= 0) break;
diff --git a/doc/crypto/blowfish.pod b/doc/crypto/blowfish.pod
index 5b2d274c15..31438ab73a 100644
--- a/doc/crypto/blowfish.pod
+++ b/doc/crypto/blowfish.pod
@@ -97,16 +97,12 @@ None of the functions presented here return any value.
 =head1 NOTE
 
 Applications should use the higher level functions
-L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling the
-blowfish functions directly.
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling these
+functions directly.
 
 =head1 SEE ALSO
 
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
 L<des_modes(7)|des_modes(7)>
 
-=head1 HISTORY
-
-The Blowfish functions are available in all versions of SSLeay and OpenSSL.
-
 =cut
-
diff --git a/doc/crypto/des.pod b/doc/crypto/des.pod
index e1add56b5e..51df21a4f9 100644
--- a/doc/crypto/des.pod
+++ b/doc/crypto/des.pod
@@ -279,13 +279,6 @@ DES_enc_read() and DES_end_write().  If set to I<DES_PCBC_MODE> (the
 default), DES_pcbc_encrypt is used.  If set to I<DES_CBC_MODE>
 DES_cbc_encrypt is used.
 
-=head1 NOTES
-
-Single-key DES is insecure due to its short key size.  ECB mode is
-not suitable for most applications; see L<des_modes(7)|des_modes(7)>.
-
-The L<evp(3)|evp(3)> library provides higher-level encryption functions.
-
 =head1 BUGS
 
 DES_3cbc_encrypt() is flawed and must not be used in applications.
@@ -314,9 +307,14 @@ ANSI X3.106
 The B<des> library was written to be source code compatible with
 the MIT Kerberos library.
 
-=head1 SEE ALSO
+=head1 NOTES
+
+Applications should use the higher level functions
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling these
+functions directly.
 
-crypt(3), L<des_modes(7)|des_modes(7)>, L<evp(3)|evp(3)>, L<rand(3)|rand(3)>
+Single-key DES is insecure due to its short key size.  ECB mode is
+not suitable for most applications; see L<des_modes(7)|des_modes(7)>.
 
 =head1 HISTORY
 
@@ -354,4 +352,9 @@ MIT library.
 Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project
 (http://www.openssl.org).
 
+=head1 SEE ALSO
+
+L<des_modes(7)|des_modes(7)>,
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>
+
 =cut
diff --git a/doc/crypto/md5.pod b/doc/crypto/md5.pod
index d11d5c32cb..41a547898a 100644
--- a/doc/crypto/md5.pod
+++ b/doc/crypto/md5.pod
@@ -87,15 +87,6 @@ RFC 1319, RFC 1320, RFC 1321
 
 =head1 SEE ALSO
 
-L<sha(3)|sha(3)>, L<ripemd(3)|ripemd(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>
-
-=head1 HISTORY
-
-MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(),
-MD5_Update() and MD5_Final() are available in all versions of SSLeay
-and OpenSSL.
-
-MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and
-above.
+L<EVP_DigestInit(3)|EVP_DigestInit(3)>
 
 =cut
diff --git a/doc/crypto/mdc2.pod b/doc/crypto/mdc2.pod
index 41f648af36..2795868073 100644
--- a/doc/crypto/mdc2.pod
+++ b/doc/crypto/mdc2.pod
@@ -54,11 +54,6 @@ ISO/IEC 10118-2, with DES
 
 =head1 SEE ALSO
 
-L<sha(3)|sha(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>
-
-=head1 HISTORY
-
-MDC2(), MDC2_Init(), MDC2_Update() and MDC2_Final() are available since
-SSLeay 0.8.
+L<EVP_DigestInit(3)|EVP_DigestInit(3)>
 
 =cut
diff --git a/doc/crypto/rc4.pod b/doc/crypto/rc4.pod
index b6d3a4342c..bbf0f27f47 100644
--- a/doc/crypto/rc4.pod
+++ b/doc/crypto/rc4.pod
@@ -37,26 +37,25 @@ Since RC4 is a stream cipher (the input is XORed with a pseudo-random
 key stream to produce the output), decryption uses the same function
 calls as encryption.
 
-Applications should use the higher level functions
-L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>
-etc. instead of calling the RC4 functions directly.
-
 =head1 RETURN VALUES
 
 RC4_set_key() and RC4() do not return values.
 
 =head1 NOTE
 
-Certain conditions have to be observed to securely use stream ciphers.
-It is not permissible to perform multiple encryptions using the same
-key stream.
-
-=head1 SEE ALSO
+Applications should use the higher level functions
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling these
+functions directly.
 
-L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<rc2(3)|rc2(3)>
+It is difficult to securely use stream ciphers. For example, do not perform
+multiple encryptions using the same key stream.
 
 =head1 HISTORY
 
 RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL.
 
+=head1 SEE ALSO
+
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>
+
 =cut
diff --git a/doc/crypto/ripemd.pod b/doc/crypto/ripemd.pod
index 264bb99ae7..e5ca3ad8d3 100644
--- a/doc/crypto/ripemd.pod
+++ b/doc/crypto/ripemd.pod
@@ -39,10 +39,6 @@ RIPEMD160_Final() places the message digest in B<md>, which must have
 space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases
 the B<RIPEMD160_CTX>.
 
-Applications should use the higher level functions
-L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the
-hash functions directly.
-
 =head1 RETURN VALUES
 
 RIPEMD160() returns a pointer to the hash value. 
@@ -50,17 +46,18 @@ RIPEMD160() returns a pointer to the hash value.
 RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for
 success, 0 otherwise.
 
+=head1 NOTE
+
+Applications should use the higher level functions
+L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling these
+functions directly.
+
 =head1 CONFORMING TO
 
 ISO/IEC 10118-3 (draft) (??)
 
 =head1 SEE ALSO
 
-L<sha(3)|sha(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>
-
-=head1 HISTORY
-
-RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and
-RIPEMD160_Final() are available since SSLeay 0.9.0.
+L<EVP_DigestInit(3)|EVP_DigestInit(3)>
 
 =cut
diff --git a/doc/crypto/sha.pod b/doc/crypto/sha.pod
index 94ab7bc724..4c1ab71022 100644
--- a/doc/crypto/sha.pod
+++ b/doc/crypto/sha.pod
@@ -60,11 +60,6 @@ ANSI X9.30
 
 =head1 SEE ALSO
 
-L<ripemd(3)|ripemd(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>
-
-=head1 HISTORY
-
-SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all
-versions of SSLeay and OpenSSL.
+L<EVP_DigestInit(3)|EVP_DigestInit(3)>
 
 =cut