From: Loup Vaillant <loup@loup-vaillant.fr>
Date: Thu, 23 Nov 2017 20:06:12 +0000 (+0100)
Subject: Reviewing  mikejsavage's manual tweaks
X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=bcccbd1da7bf0755feee40d04d2e336588c1127c;p=Monocypher.git

Reviewing  mikejsavage's manual tweaks
---

diff --git a/doc/man/man3/crypto_argon2i.3monocypher b/doc/man/man3/crypto_argon2i.3monocypher
index 8e9b3c1..1631801 100644
--- a/doc/man/man3/crypto_argon2i.3monocypher
+++ b/doc/man/man3/crypto_argon2i.3monocypher
@@ -64,8 +64,7 @@ Must be
 .Fa nb_blocks
 × 1024 bytes big, and suitably aligned for 64-bit integers.
 .Fn malloc
-will yield a suitable chunk of memory on platforms that support 64-bit types
-(e.g. int64_t or IEEE double precision floats).
+will yield a suitable chunk of memory.
 .Pp
 The work area is automatically wiped by
 .Fn crypto_argon2i .
@@ -146,8 +145,8 @@ to compare password hashes to prevent timing attacks.
 .Pp
 To select the nb_blocks and nb_iterations parameters, it should first be
 decided how long the computation should take.
-For user authentication, somewhere between half a second (convenient)
-and several seconds (paranoid) is a good starting point.
+For user authentication, we recommend somewhere between half a second
+(convenient) and several seconds (paranoid).
 The computation should use as much memory as can be spared.
 .Pp
 Since parameter selection depends on your hardware, some trial and error
@@ -159,7 +158,6 @@ Adjust
 first.
 If using all available memory is not slow enough, increase
 .Fa nb_iterations .
-.El
 .Sh RETURN VALUES
 This function returns nothing.
 .Sh EXAMPLES
diff --git a/doc/man/man3/crypto_lock.3monocypher b/doc/man/man3/crypto_lock.3monocypher
index 06cf36d..0f8a015 100644
--- a/doc/man/man3/crypto_lock.3monocypher
+++ b/doc/man/man3/crypto_lock.3monocypher
@@ -91,10 +91,11 @@ authentication key associated with that nonce.
 The MAC is intended to be sent along with the ciphertext.
 .It Fa plain_text
 The secret message.
-Its content will be kept hidden from attackers.
+Its contents will be kept hidden from attackers.
 Its length however, will
 .Em not .
-Be careful when combining encryption with compression. See
+Be careful when combining encryption with compression.
+See
 .Xr intro 3monocypher
 for details.
 .It Fa cipher_text
@@ -153,8 +154,8 @@ appended to
 so it gets authenticated, and should be extracted from the end of the
 message when decrypting.
 Otherwise an attacker could provide a false length, effectively moving
-the boundary between the additional data and the ciphertext. This may
-cause buffer overflows in some programs.
+the boundary between the additional data and the ciphertext.
+This may cause buffer overflows in some programs.
 .El
 .Pp
 An incremental interface is available; see
@@ -179,7 +180,7 @@ and
 Corruption can happen because of transmission errors, programmer
 error, or an attacker's interference.
 .Fa plain_text
-does not need wiping if the decryption fails.
+does not need to be wiped if the decryption fails.
 .Sh EXAMPLES
 Encryption:
 .Bd -literal -offset indent
@@ -219,9 +220,10 @@ size_t         text_size;    /* Message size (NOT secret) */
 uint8_t       *plain_text;   /* Secret message            */
 if (crypto_unlock(plain_text, key, nonce, mac,
                   cipher_text, text_size)) {
-    /* The message is corrupted           */
-    /* Wipe key if it is no longer needed */
-    /* and abort the decryption           */
+    /* The message is corrupted.
+     * Wipe key if it is no longer needed,
+     * and abort the decryption.
+     */
     crypto_wipe(key, 32);
 }
 /* Wipe secrets if they are no longer needed */
@@ -237,9 +239,10 @@ const uint8_t  mac  [16];    /* Received from the network */
 uint8_t       *text;         /* Message to decrypt        */
 size_t         text_size;    /* Message size (NOT secret) */
 if (crypto_unlock(text, key, nonce, mac, text, text_size)) {
-    /* The message is corrupted           */
-    /* Wipe key if it is no longer needed */
-    /* and abort the decryption           */
+    /* The message is corrupted.
+     * Wipe key if it is no longer needed,
+     * and abort the decryption.
+     */
     crypto_wipe(key, 32);
 }
 /* Wipe secrets if they are no longer needed */
diff --git a/doc/man/man3/intro.3monocypher b/doc/man/man3/intro.3monocypher
index fd23c26..b4b01fd 100644
--- a/doc/man/man3/intro.3monocypher
+++ b/doc/man/man3/intro.3monocypher
@@ -176,7 +176,6 @@ The Poly1305 authenticator, X25519, and EdDSA use multiplication.
 Some older processors do not multiply in constant time.
 If the target platform is something other than x86, x86_64, ARM or
 ARM64, double check how it handles multiplication.
-.Pp
 .Ss Data compression
 Encryption does not hide the length of the input plaintext.
 Most compression algorithms work by using fewer bytes to encode