Manual review: applying CuleX's advice

diff --git a/doc/man/man3/intro.3monocypher b/doc/man/man3/intro.3monocypher
index 0e01de8dac8fe00ac76503362a044f44e2c32fcb..0a3b3897f919fdbf557211c06d549fac76b3999a 100644 (file)
--- a/doc/man/man3/intro.3monocypher
+++ b/doc/man/man3/intro.3monocypher
@@ -27,7 +27,7 @@ It is very fast and very simple.
 implements the Blake2b hash.
 Blake2b combines the security of SHA-3 and the speed of MD5.
 It is immune to length extension attacks and provides a keyed mode
-that makes it a very safe authenticator.
+that makes it a safe, easy to use authenticator.
 .Ss Password key derivation
 .Xr crypto_argon2i 3monocypher
 implements the Argon2i resource intensive hash algorithm.
@@ -36,17 +36,17 @@ Unlike Scrypt, Argon2i is immune to timing attacks.
 .Ss Key exchange
 .Xr crypto_key_exchange 3monocypher
 implements X25519, an elliptic curve Diffie Hellman key exchange
-algorithm based on curve25519.
+algorithm based on Curve25519.
 X25519 derives a shared secret from two private/public key pairs.
 It is fast, simple, and relatively easy to implement securely.
 .Ss Public key signatures
 .Xr crypto_sign 3monocypher
 and
 .Xr crypto_check 3monocypher
-implement EdDSA, with curve 25519 and Blake2b.
+implement EdDSA, with Curve25519 and Blake2b.
 This is the same as the more famous Ed25519, with SHA-512 replaced by
-the more modern Blake2b.
-Ed25519 is supported as a compilation option.
+the faster and more secure Blake2b.
+Ed25519 (EdDSA with SHA-512), is supported as a compilation option.
 .Ss Constant time comparison
 .Xr crypto_verify16 3monocypher ,
 .Xr crypto_verify32 3monocypher ,
@@ -110,10 +110,8 @@ the chances of leaks.
 Using cryptography securely is difficult.
 Flaws that never manifest under normal use might be exploited by a
 clever adversary.
-Cryptography itself is counter intuitive, and cryptographic libraries
-are easy to misuse.
-Despite its simplicity, even Monocypher allows a number of fatal
-mistakes.
+Cryptographic libraries are easy to misuse.
+Even Monocypher allows a number of fatal mistakes.
 .Pp
 Users should follow a formal introduction to cryptography.
 We currently recommend the https://www.crypto101.io/ online course.
@@ -152,8 +150,11 @@ The
 .Pa /dev/urandom
 special file may be used on systems that do not provide an easy to use
 system call.
-Being a file makes it harder to use correctly (reads may be aborted
-halfway through).
+Be careful, though: being a file makes
+.Pa /dev/urandom
+hard to use correctly and securely.
+Reads may be interrupted, and more attacks are possible on a file than
+on a system call.
 .Ss Timing attacks
 Monocypher runs in "constant time".
 There is no flow from secrets to timings.
@@ -171,10 +172,8 @@ They tend to stop as soon as a difference is spotted.
 In many cases, this enables attackers to recover the secrets and
 destroy all security.
 .Pp
-The Poly1305 authenticator, X25519, and EdDSA use the multiplication
-instruction.
-Some older processors do not run this instruction in constant time.
-They are no longer in use, though.
+The Poly1305 authenticator, X25519, and EdDSA use multiplication.
+Some older processors do not multiply in constant time.
 .Pp
 .Sy The lengths of the inputs are not secret.
 Timings do reveal them \(en So do network traffic and file sizes.
@@ -184,7 +183,7 @@ Sometimes however they do.
 It has happened before with variable-length voice encoding software.
 The researchers managed to identify the speakers and recover parts of
 the conversation.
-.Ss Forward secrecy.
+.Ss Forward secrecy
 Long term secrets cannot be expected to stay safe indefinitely.
 Users may reveal them by mistake, or the host computer might have a
 vulnerability and be compromised.
@@ -193,12 +192,9 @@ are not compromised even if the long term keys are.
 This is done by generating temporary keys, then encrypting messages
 with them.
 .Pp
-This can be generalised.
-To the extent possible, secrets that went through a computer should not
-be compromised when this computer is stolen or infected at a later
+This can be generalised: secrets that went through a computer should
+not be compromised when this computer is stolen or infected at a later
 point.
-This generally means making sure those secrets are erased when no
-longer used.
 .Pp
 A first layer of defence is to explicitly wipe secrets as soon as
 they are no longer used.
@@ -221,16 +217,12 @@ Another way is to encrypt the swap partition (this is less safe).
 Finally, swap can be disabled locally \(en this is often the only
 way.
 .Pp
-To disable swap on specific memory regions, UNIX systems provide
-.Fn mlock .
-Windows has
+UNIX systems can disable swap for specific buffers with
+.Fn mlock ,
+and disable swap for the whole process with
+.Fn mlockall .
+Windows can disable swap for specific buffers with
 .Fn VirtualLock .
-UNIX systems also provide the
-.Fn mlockall
-system call, which locks
-.Em all
-memory used by a single process.
-Though possibly overkill, this is easier to use safely.
 .Pp
 Note: core dumps cause similar problems.
 Disable them.