Manual review: verify, wipe, memcmp

Rephrased a bit.
Removed references to the rest of Monocypher.  That advice
belongs to the Blake2b and Argon2i pages.

diff --git a/doc/man/man3/crypto_verify16.3monocypher b/doc/man/man3/crypto_verify16.3monocypher
index cc11e686dea2ea8478dc801214130b148afe30d4..fead04ecc2f15f148b58dd09b5ec18ee2263c0ee 100644 (file)
--- a/doc/man/man3/crypto_verify16.3monocypher
+++ b/doc/man/man3/crypto_verify16.3monocypher
@@ -17,14 +17,19 @@
 .Sh DESCRIPTION
 Cryptographic operations often require comparison of secrets or values
 derived from secrets.
-Take for example a message authentication code (MAC).
+Standard comparison functions tend to exit as soo as they find a
+difference, and doing so leaks information through variable timings.
+.Pp
+A cannonical example is the message authentication code (MAC).
 A MAC may be sent over the network along with a message.
 However, the correct MAC is secret.
-If the attacker attempts a forgery, you do not want to reveal
+If the attacker attempts a forgery, one does not want to reveal
 .Dq your MAC is wrong, Em and it took 384 microseconds to tell .
 If the next attempt takes 462 microseconds instead, it gives away the
 fact that the attacker just guessed a few bytes correctly.
-That way, an attacker can derive the correct MAC.
+That way, an attacker can derive the correct MAC, and sucessfully
+forge a message.
+This has lead to practical attacks in the past.
 .Pp
 To avoid such catastrophic failure,
 the
@@ -33,46 +38,14 @@ the
 and
 .Fn crypto_verify64
 functions provide comparison functions whose timing is independent from
-the context of their input.
-.Pp
-The
-.Fn crypto_verify16 ,
-.Fn crypto_verify32
-and
-.Fn crypto_verify64
-functions compare the first
-16, 32 and 64 bytes of the two byte arrays
+the content of their input.
+They compare the first
+16, 32, or 64 bytes of the two byte arrays
 .Fa a
 and
-.Fa b ,
-respectively.
-.Pp
-You should not need these functions if you use the high-level interface
-of Monocypher \(en just look at the return codes.
-Some high-level functions in Monocypher nonetheless require manual
-constant-time comparison:
-.Bl -bullet
-.It
-.Xr crypto_argon2i 3monocypher
-when used for password storage.
-Comparing the input password hash with the one in the database must be
-constant-time.
-.It
-.Xr crypto_blake2b 3monocypher
-when used with the
-.Fa key
-argument to create a message authentication code.
-Comparing the local hash with a known good hash must be constant-time.
-.El
-.Pp
-Both of these functions allow you to specify output lengths that do not
-have an equivalent verification function.
-In this case, you may wish to allocate buffers larger than your output
-hash, zero them out, copy the hashes into the buffers and compare those
-buffers instead.
+.Fa b .
 .Pp
-If you are in doubt whether you need to use these functions, prefer
-these over
+When in doubt, prefer these over
 .Fn memcmp .
 .Sh RETURN VALUES
 These functions return 0 if the two memory chunks are the same, -1