diff options
| -rw-r--r-- | doc/manual/block_cipher.rst | 14 | ||||
| -rw-r--r-- | doc/manual/cipher_modes.rst | 12 |
2 files changed, 16 insertions, 10 deletions
diff --git a/doc/manual/block_cipher.rst b/doc/manual/block_cipher.rst index 2ee8ffde0..85daeee99 100644 --- a/doc/manual/block_cipher.rst +++ b/doc/manual/block_cipher.rst @@ -9,6 +9,9 @@ operations such as authenticated encryption. In almost all cases, a bare block cipher is not what you should be using. You probably want an authenticated cipher mode instead (see :ref:`cipher_modes`) + This interface is used to build higher level operations (such as cipher + modes or MACs), or in the very rare situation where ECB is required, + eg for compatability with an existing system. .. cpp:class:: BlockCipher @@ -157,7 +160,8 @@ 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. +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. .. warning:: Avoid any 64-bit block cipher in new designs. There are combinatoric issues that affect any 64-bit cipher that render it @@ -174,8 +178,6 @@ implementations typically are vulnerable to side channel attacks. For x86 systems with SSSE3 but without AES-NI, Botan has an implementation which avoids known side channels. -If you are developing new code and have no particular opinion, pick AES-256. - Available if ``BOTAN_HAS_AES`` is defined. ARIA @@ -230,8 +232,10 @@ Available if ``BOTAN_HAS_CASCADE`` is defined. DES, 3DES, DESX ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Originally designed by IBM and NSA in the 1970s. Very slow, but still common in -some industries such as finance. Avoid in new code. +Originally designed by IBM and NSA in the 1970s. Today, DES's 56-bit key renders +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. Available if ``BOTAN_HAS_DES`` is defined. diff --git a/doc/manual/cipher_modes.rst b/doc/manual/cipher_modes.rst index e7a147d25..75e7dd072 100644 --- a/doc/manual/cipher_modes.rst +++ b/doc/manual/cipher_modes.rst @@ -184,11 +184,13 @@ will be returned by :cpp:func:`get_cipher` if the named cipher is an AEAD mode). .. cpp:function:: void start(const uint8_t nonce[], size_t nonce_len) Start processing a message, using *nonce* as the unique per-message - value. + value. It does not need to be random, simply unique (per key). .. warning:: - With most AEADs, if the same nonce is ever used to encrypt two - different messages under the same key, all security is lost. + With almost all AEADs, if the same nonce is ever used to encrypt two + different messages under the same key, all security is lost. If + reliably generating unique nonces is difficult in your environment, + use SIV mode which retains security even if nonces are repeated. .. cpp:function:: void update(secure_vector<uint8_t>& buffer, size_t offset = 0) @@ -303,5 +305,5 @@ CCM Available if ``BOTAN_HAS_AEAD_CCM`` is defined. -Requires a 128-bit block cipher. This is a NIST standard mode but that is about -all to recommenmd it. Prefer EAX. +A composition of CTR mode and CBC-MAC. Requires a 128-bit block cipher. This is +a NIST standard mode, but that is about all to recommend it. Prefer EAX. |