From 819ca27417406252144e06e268468426abf74120 Mon Sep 17 00:00:00 2001 From: Fabio Scotoni <34964387+fscoto@users.noreply.github.com> Date: Wed, 25 Mar 2020 11:25:37 +0100 Subject: [PATCH] Address review concerns in #162 --- doc/man/man3/crypto_from_eddsa_private.3monocypher | 12 ++++++------ doc/man/man3/crypto_x25519_dirty_fast.3monocypher | 2 +- doc/man/man3/crypto_x25519_inverse.3monocypher | 9 ++++++--- doc/man/man3/intro.3monocypher | 7 ++++--- 4 files changed, 17 insertions(+), 13 deletions(-) diff --git a/doc/man/man3/crypto_from_eddsa_private.3monocypher b/doc/man/man3/crypto_from_eddsa_private.3monocypher index 4bb5784..01bd411 100644 --- 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 63df34f..a8a61e8 100644 --- 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 862cbd1..30a2086 100644 --- 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 5862f56..f82da56 100644 --- a/doc/man/man3/intro.3monocypher +++ b/doc/man/man3/intro.3monocypher @@ -50,7 +50,7 @@ .\" with this software. If not, see .\" .\" -.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 -- 2.47.3