diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api_ref/block_cipher.rst | 48 | ||||
| -rw-r--r-- | doc/api_ref/hash.rst | 20 | ||||
| -rw-r--r-- | doc/api_ref/message_auth_codes.rst | 17 | ||||
| -rw-r--r-- | doc/deprecated.rst | 6 |
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 |