Address review concerns in #162

diff --git a/doc/man/man3/crypto_from_eddsa_private.3monocypher b/doc/man/man3/crypto_from_eddsa_private.3monocypher
index 4bb5784f0676fe4d9f4768178c7876e811e482e9..01bd411997b79949d9ba19fbcea617926ab10157 100644 (file)
--- a/doc/man/man3/crypto_from_eddsa_private.3monocypher
+++ b/doc/man/man3/crypto_from_eddsa_private.3monocypher
@@ -77,7 +77,7 @@ and
 .Xr crypto_x25519 3monocypher .
 This may be useful in some resource-constrained contexts or when no
 other key is available (for example, when retrieving SSH public keys
-from GitHub and reusing the SSH private keys as X25519 public keys).
+from GitHub and reusing the SSH public keys as X25519 public keys).
 .Pp
 The
 .Fn crypto_from_eddsa_private
@@ -85,7 +85,7 @@ function converts an EdDSA (with BLAKE2b) private key to an X25519
 private key.
 The
 .Fn crypto_from_eddsa_public
-function converts an EdDSA private key to an X25519 public key.
+function converts an EdDSA public key to an X25519 public key.
 .Pp
 X25519 key pairs cannot be converted back to EdDSA key pairs.
 The conversion of private keys is specific to EdDSA with BLAKE2b because
@@ -126,7 +126,7 @@ functions first appeared in Monocypher 3.1.0.
 .Sh SECURITY CONSIDERATIONS
 It is generally considered poor form to reuse the same key for different
 purposes.
-While this conversion is technically safe
-avoid these functions unless you are particularly resource-constrained
-or otherwise have a hard requirement nonetheless.
-It is otherwise an unnecessary risk factor.
+While this conversion is technically safe,
+avoid these functions nonetheless unless you are particularly
+resource-constrained or have some other kind of hard requirement.
+It is an unnecessary risk factor.

diff --git a/doc/man/man3/crypto_x25519_dirty_fast.3monocypher b/doc/man/man3/crypto_x25519_dirty_fast.3monocypher
index 63df34fdf3f4bc0c0bef7a471a33993a45b4058c..a8a61e832d0b693de701b060d55417bab29861f9 100644 (file)
--- a/doc/man/man3/crypto_x25519_dirty_fast.3monocypher
+++ b/doc/man/man3/crypto_x25519_dirty_fast.3monocypher
@@ -105,7 +105,7 @@ The resulting public keys are to be used with
 .Xr crypto_x25519 3monocypher
 and
 .Xr crypto_key_exchange 3monocypher ,
-which clear the cofactor,
+which clear the cofactor.
 .Sh RETURN VALUES
 These functions have no return value.
 They cannot fail.

diff --git a/doc/man/man3/crypto_x25519_inverse.3monocypher b/doc/man/man3/crypto_x25519_inverse.3monocypher
index 862cbd1a0193d80881ef70a3f564ae5952b69d42..30a2086b908fc783cff4cff303558017d9a3315c 100644 (file)
--- a/doc/man/man3/crypto_x25519_inverse.3monocypher
+++ b/doc/man/man3/crypto_x25519_inverse.3monocypher
@@ -85,9 +85,12 @@ The arguments are:
 The output point.
 .It Fa private_key
 The private key (scalar) to use.
-This value's cofactor is cleared first,
-the multiplicative inverse (modulo the curve order) has its cofactor
-cleared and is then used for scalar multiplication.
+First, the value is clamped;
+then the clamped value's multiplicative inverse (modulo the curve order)
+is determined;
+the clamped value's multiplicative inverse then has its cofactor
+cleared,
+and that final value is then used for scalar multiplication.
 .It Fa curve_point
 The curve point on X25519 to multiply with the multiplicative inverse
 (modulo the curve order) of

diff --git a/doc/man/man3/intro.3monocypher b/doc/man/man3/intro.3monocypher
index 5862f56277b1b032b5521afdb8553137e480a9b8..f82da56b51c5db7217fb504ecf27bae875d3dd6a 100644 (file)
--- a/doc/man/man3/intro.3monocypher
+++ b/doc/man/man3/intro.3monocypher
@@ -50,7 +50,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd March 24, 2020
+.Dd March 25, 2020
 .Dt INTRO 3MONOCYPHER
 .Os
 .Sh NAME
@@ -102,10 +102,11 @@ 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.
 .Pp
-For specialized protocols that require indistinguishability from random
+For specialised protocols that require indistinguishability from random
 noise,
 .Xr crypto_curve_to_hidden 3monocypher
-gives the option to disguise X25519 public keys as random noise.
+gives the option to disguise ephemeral (one-time use) X25519 public keys
+as random noise.
 .Ss Public key signatures
 .Xr crypto_sign 3monocypher
 and