Documentation and deprecation updates

Deprecate XTEA, GOST cipher, and Tiger.

GOST cipher is (AFAIK) no longer approved in Russia, so no reason
to keep it.

XTEA is obscure. Only reason it was saved in the last round of
deprecations was its existance in Golang's x/crypto - but now x/crypto
has deprecated it, so ...

Found out today that Tiger has a full-round preimage attack.  Not
practical but still... and with it being almost never used or
implemented, more than enough to push it onto the deprecation list.

4 files changed, 67 insertions, 24 deletions

diff --git a/doc/api_ref/block_cipher.rst b/doc/api_ref/block_cipher.rst
index 578235a2d..7b1159487 100644
--- a/doc/api_ref/block_cipher.rst
+++ b/doc/api_ref/block_cipher.rst
@@ -157,11 +157,11 @@ block of plaintext with AES-256 using two different keys.
 Available Ciphers
 ---------------------
 
-Botan includes a number of block ciphers that are specific to particular
-countries, as well as a few that are included mostly due to their use in
-specific protocols such as PGP but not widely used elsewhere. The ciphers that
-seem best for new code are AES, Serpent, and Threefish-512. If you are
-developing new code and have no particular opinion, pick AES-256.
+Botan includes a number of block ciphers that are specific to particular countries, as
+well as a few that are included mostly due to their use in specific protocols such as PGP
+but not widely used elsewhere. If you are developing new code and have no particular
+opinion, use AES-256. If you desire an alternative to AES, consider Serpent, SHACAL2 or
+Threefish.
 
 .. warning:: Avoid any 64-bit block cipher in new designs. There are
              combinatoric issues that affect any 64-bit cipher that render it
@@ -206,17 +206,20 @@ CAST-256
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A 128-bit cipher that was a contestant in the NIST AES competition.
-Rarely used, and now deprecated in Botan. Use AES or Serpent instead.
+Almost never used in practice. Prefer AES or Serpent.
 
 Available if ``BOTAN_HAS_CAST256`` is defined.
 
+.. warning::
+   Support for CAST-256 is deprecated and will be removed in a future major release.
+
 Camellia
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Comes in three variants, Camellia-128, Camellia-192, and Camellia-256.
 
-A Japanese design standardized by ISO, NESSIE and CRYPTREC. Somewhat common.
-Prefer AES or Serpent in new designs.
+A Japanese design standardized by ISO, NESSIE and CRYPTREC.
+Rarely used outside of Japan.
 
 Available if ``BOTAN_HAS_CAMELLIA`` is defined.
 
@@ -237,16 +240,22 @@ it insecure to any well-resourced attacker. DESX and 3DES extend the key length,
 and are still thought to be secure, modulo the limitation of a 64-bit block.
 All are somewhat common in some industries such as finance. Avoid in new code.
 
+.. warning::
+   Support for DESX is deprecated and it will be removed in a future major release.
+
 Available if ``BOTAN_HAS_DES`` is defined.
 
 GOST-28147-89
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A old 64-bit Russian cipher. Possible security issues. Avoid unless
-compatibility is needed.
+Aka "Magma". An old 64-bit Russian cipher. Possible security issues, avoid
+unless compatibility is needed.
 
 Available if ``BOTAN_HAS_GOST_28147_89`` is defined.
 
+.. warning::
+   Support for this cipher is deprecated and will be removed in a future major release.
+
 IDEA
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -263,6 +272,9 @@ it outside of this context.
 
 Available if ``BOTAN_HAS_KASUMI`` is defined.
 
+.. warning::
+   Support for Kasumi is deprecated and will be removed in a future major release.
+
 Lion
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -277,12 +289,13 @@ MISTY1
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A 64-bit Japanese cipher standardized by NESSIE and ISO. Seemingly secure, but
-quite slow and saw little adoption. No reason to use it in new code. The
-implementation in Botan is deprecated, and it is likely to be removed in a
-future release.
+quite slow and saw little adoption. No reason to use it in new code.
 
 Available if ``BOTAN_HAS_MISTY1`` is defined.
 
+.. warning::
+   Support for MISTY1 is deprecated and will be removed in a future major release.
+
 Noekeon
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -294,7 +307,7 @@ Available if ``BOTAN_HAS_NOEKEON`` is defined.
 SEED
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A older South Korean cipher, widely used in industry there.
+A older South Korean cipher, widely used in industry there. No reason to choose it otherwise.
 
 Available if ``BOTAN_HAS_SEED`` is defined.
 
@@ -319,8 +332,8 @@ Available if ``BOTAN_HAS_SM4`` is defined.
 Serpent
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-An AES contender. Widely considered the most conservative design. Fairly slow,
-especially if no SIMD instruction set is available.
+An AES contender. Widely considered the most conservative design. Fairly slow
+unless SIMD instructions are available.
 
 Available if ``BOTAN_HAS_SERPENT`` is defined.
 
@@ -335,7 +348,8 @@ Available if ``BOTAN_HAS_THREEFISH_512`` is defined.
 Twofish
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-An AES contender. Somewhat complicated key setup and a "kitchen sink" design.
+A 128-bit block cipher that was one of the AES finalists. Has a somewhat complicated key
+setup and a "kitchen sink" design.
 
 Available if ``BOTAN_HAS_TWOFISH`` is defined.
 
diff --git a/doc/api_ref/hash.rst b/doc/api_ref/hash.rst
index ec83b7f16..533a7267b 100644
--- a/doc/api_ref/hash.rst
+++ b/doc/api_ref/hash.rst
@@ -126,11 +126,18 @@ Named like "Blake2b" which selects default 512-bit output, or as
 GOST-34.11
 ^^^^^^^^^^^^^^^
 
+.. deprecated:: 2.11
+
 Available if ``BOTAN_HAS_GOST_34_11`` is defined.
 
 Russian national standard hash. It is old, slow, and has some weaknesses. Avoid
 it unless you must.
 
+.. warning::
+   As this hash function is no longer approved by the latest Russian standards,
+   support for GOST 34.11 hash is deprecated and will be removed in a future
+   major release.
+
 Keccak-1600
 ^^^^^^^^^^^^^^^
 
@@ -185,8 +192,9 @@ SHA-512
 
 Available if ``BOTAN_HAS_SHA2_64`` is defined.
 
-SHA-512 is faster than SHA-256 on 64-bit processors. Also includes
-the truncated variants SHA-384 and SHA-512/256.
+SHA-512 is faster than SHA-256 on 64-bit processors. Also includes the
+truncated variants SHA-384 and SHA-512/256, which have the advantage
+of avoiding message extension attacks.
 
 SHA-3
 ^^^^^^^^^^^^^^^
@@ -258,6 +266,8 @@ unless compatibility is needed.
 Tiger
 ^^^^^^^^^^^^^^^
 
+.. deprecated:: 2.15
+
 Available if ``BOTAN_HAS_TIGER`` is defined.
 
 An older 192-bit hash function, optimized for 64-bit systems. Possibly
@@ -267,6 +277,12 @@ Tiger supports variable length output (16, 20 or 24 bytes) and
 variable rounds (which must be at least 3). Default is 24 byte output
 and 3 rounds. Specify with names like "Tiger" or "Tiger(20,5)".
 
+.. warning::
+  There are documented (albeit impractical) attacks on the full Tiger
+  hash leading to preimage attacks. This indicates possibility of a
+  serious weakness in the hash and for this reason it is deprecated
+  and will be removed in a future major release of the library.
+
 Whirlpool
 ^^^^^^^^^^^^^^^
 
diff --git a/doc/api_ref/message_auth_codes.rst b/doc/api_ref/message_auth_codes.rst
index 70b6c9c3b..a3391a310 100644
--- a/doc/api_ref/message_auth_codes.rst
+++ b/doc/api_ref/message_auth_codes.rst
@@ -203,6 +203,9 @@ authenticated. Avoid unless required for compatibility.
 
 Available if ``BOTAN_HAS_CBC_MAC`` is defined.
 
+.. warning::
+   CBC-MAC support is deprecated and will be removed in a future major release.
+
 CMAC
 ~~~~~~~~~~~~
 
@@ -221,6 +224,10 @@ lost.
 
 Available if ``BOTAN_HAS_GMAC`` is defined.
 
+.. warning::
+   Due to the nonce requirement, GMAC is exceptionally fragile. Avoid it unless
+   absolutely required.
+
 HMAC
 ~~~~~~~~~~~~
 
@@ -237,6 +244,10 @@ message, or all security is lost.
 
 Available if ``BOTAN_HAS_POLY1305`` is defined.
 
+.. warning::
+   Due to the nonce requirement, Poly1305 is exceptionally fragile. Avoid it unless
+   absolutely required.
+
 SipHash
 ~~~~~~~~~~~~
 
@@ -249,7 +260,9 @@ Available if ``BOTAN_HAS_SIPHASH`` is defined.
 X9.19-MAC
 ~~~~~~~~~~~~
 
-A CBC-MAC variant sometimes used in finance. Always uses DES. Avoid unless
-required.
+A CBC-MAC variant sometimes used in finance. Always uses DES.
+Sometimes called the "DES retail MAC", also standardized in ISO 9797-1.
+
+It is slow and has known attacks. Avoid unless required.
 
 Available if ``BOTAN_HAS_X919_MAC`` is defined.
diff --git a/doc/deprecated.rst b/doc/deprecated.rst
index 4a992dd6f..f96a1b41b 100644
--- a/doc/deprecated.rst
+++ b/doc/deprecated.rst
@@ -59,14 +59,14 @@ Deprecated Functionality
 This section lists cryptographic functionality which will be removed
 in a future major release.
 
-- Block ciphers CAST-256, Kasumi, MISTY1, and DESX.
+- Block ciphers CAST-256, GOST 28147, Kasumi, MISTY1, DESX, and XTEA.
+
+- Hash functions GOST 34.11-94 and Tiger
 
 - DLIES
 
 - MCEIES
 
-- GOST 34.11-94 hash
-
 - CBC-MAC
 
 - PBKDF1 key derivation