Small doc tweaks

3 files changed, 19 insertions, 7 deletions

diff --git a/doc/manual/cipher_modes.rst b/doc/manual/cipher_modes.rst
index 078c4d935..553f883a0 100644
--- a/doc/manual/cipher_modes.rst
+++ b/doc/manual/cipher_modes.rst
@@ -260,6 +260,9 @@ Available AEAD Modes
 -------------------------
 
 If in doubt about what to use, pick ChaCha20Poly1305, AES-256/GCM, or AES-256/SIV.
+Both ChaCha20Poly1305 and AES with GCM are widely implemented. SIV is somewhat
+more obscure (and is slower than either GCM or ChaCha20Poly1305), but has
+excellent security properites.
 
 ChaCha20Poly1305
 ~~~~~~~~~~~~~~~~~~
diff --git a/doc/manual/pbkdf.rst b/doc/manual/pbkdf.rst
index ba0f464a0..5d0da9e95 100644
--- a/doc/manual/pbkdf.rst
+++ b/doc/manual/pbkdf.rst
@@ -28,11 +28,11 @@ the secret will be stored in memory that will not be zeroed.
       Run the PBKDF algorithm for the specified number of iterations,
       with the given salt, and write output to the buffer.
 
-   .. cpp:function:: void pbkdf_timed(uint8_t out[], size_t out_len,
-                         const std::string& passphrase,
-                         const uint8_t salt[], size_t salt_len,
-                         std::chrono::milliseconds msec,
-                         size_t& iterations) const;
+   .. cpp:function:: void pbkdf_timed(uint8_t out[], size_t out_len, \
+                         const std::string& passphrase, \
+                         const uint8_t salt[], size_t salt_len, \
+                         std::chrono::milliseconds msec, \
+                         size_t& iterations) const
 
       Choose (via short run-time benchmark) how many iterations to perform
       in order to run for roughly msec milliseconds. Writes the number
diff --git a/doc/manual/stream_ciphers.rst b/doc/manual/stream_ciphers.rst
index 0eaaa7716..96ec9f422 100644
--- a/doc/manual/stream_ciphers.rst
+++ b/doc/manual/stream_ciphers.rst
@@ -7,8 +7,17 @@ of the cipher and encryption of plaintext with arbitrary length is possible in
 one go (in byte amounts). All implemented stream ciphers derive from the base
 class :cpp:class:`StreamCipher` (`botan/stream_cipher.h`).
 
-Note that some of the implemented stream ciphers require a fresh initialisation
-vector.
+.. warning::
+
+   Using a stream cipher without an authentication code is extremely insecure,
+   because an attacker can trivially modify messages. Prefer using an
+   authenticated cipher mode such as GCM or SIV.
+
+.. warning::
+
+   Encrypting more than one message with the same key requires careful management
+   of initialization vectors. Otherwise the keystream will be reused, which causes
+   the security of the cipher to completely fail.
 
 .. cpp:class:: StreamCipher