Minor doc updates

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.