Update intro.3monocypher a bit

diff --git a/doc/intro.3monocypher b/doc/intro.3monocypher
index d93f0dd2db2bb3c9699c3cf97e3f1975cc889e9d..a02863e2e8b4a0d0dde21c9e16aea570a66ac071 100644 (file)
--- a/doc/intro.3monocypher
+++ b/doc/intro.3monocypher
@@ -50,7 +50,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd February 13, 2022
+.Dd February 20, 2022
 .Dt INTRO 3MONOCYPHER
 .Os
 .Sh NAME
@@ -65,6 +65,8 @@ hashing and key derivation, key exchange, and public key signatures.
 and
 .Xr crypto_aead_unlock 3monocypher
 use the ChaCha20 cipher and the Poly1305 one-time authenticator.
+There is also an incremental interface to facilitate
+file encryption and encrypted streams.
 .Pp
 ChaCha20 is a stream cipher based on a cryptographic hash function.
 It runs efficiently on a wide variety of hardware, and unlike AES
@@ -73,15 +75,6 @@ naturally runs in constant time on all hardware.
 Poly1305 is a one-time authenticator, derived from Carter & Wegman
 universal hashing.
 It is very fast and very simple.
-.Pp
-For specialised needs,
-.Xr crypto_chacha20_djb 3monocypher
-and
-.Xr crypto_poly1305 3monocypher
-are available to implement constructions involving them.
-Whenever possible,
-.Xr crypto_aead_lock 3monocypher
-should be preferred, however.
 .Ss Hashing
 .Xr crypto_blake2b 3monocypher
 implements the BLAKE2b hash.
@@ -90,11 +83,11 @@ It is immune to length extension attacks and provides a keyed mode
 that makes it a safe, easy to use authenticator.
 .Ss Password hashing and key derivation
 .Xr crypto_argon2 3monocypher
-implements the Argon2i resource intensive hash algorithm,
+implements the Argon2 resource intensive hash algorithm,
 which can be used to hash passwords for storage and to derive keys
 from passwords.
 Argon2 won the password hashing competition in 2015.
-Unlike scrypt, Argon2i is immune to timing attacks.
+Unlike scrypt, the Argon2i variant is immune to timing attacks.
 .Ss Key exchange (Public Key Cryptography)
 .Xr crypto_x25519 3monocypher
 implements X25519, an elliptic curve Diffie Hellman key exchange
@@ -113,7 +106,7 @@ and
 .Xr crypto_eddsa_check 3monocypher
 implement EdDSA, with Curve25519 and BLAKE2b.
 This is the same as the more famous Ed25519, with SHA-512 replaced by
-the faster and more secure BLAKE2b.
+the faster BLAKE2b.
 .Ss Constant time comparison
 .Xr crypto_verify16 3monocypher ,
 .Xr crypto_verify32 3monocypher ,
@@ -204,17 +197,16 @@ Make sure your inputs are correct.
 Using cryptography securely is difficult.
 Flaws that never manifest under normal use might be exploited by a
 clever adversary.
-Cryptographic libraries are easy to misuse.
-Even Monocypher allows a number of fatal mistakes.
+Cryptographic libraries are easy to catastrophically misuse,
+and Monocypher is no exception.
 .Pp
 Users should follow a formal introduction to cryptography.
 We currently recommend the
 .Lk https://www.crypto101.io/ "Crypto 101 online course" .
 .Ss Random number generation
 Use the facilities of your operating system.
-Avoid user space random number generators.
-They are easy to misuse, which has led to countless vulnerabilities
-in the past.
+Avoid user space random number generators,
+whose misuse has led to countless vulnerabilities in the past.
 For instance, the random stream may be repeated if one is not careful
 with multi-threading, and forward secrecy is lost without proper key
 erasure.
@@ -265,7 +257,7 @@ or
 .Xr crypto_verify64 3monocypher .
 Do not use standard comparison functions.
 They tend to stop as soon as a difference is spotted.
-In many cases, this enables attackers to recover the secrets and
+In many cases this enables attackers to recover the secrets and
 destroy all security.
 .Pp
 The Poly1305 authenticator, X25519, and EdDSA use multiplication.