From: CuleX <cculex@gmail.com>
Date: Thu, 7 Sep 2017 04:52:11 +0000 (+0200)
Subject: Clarify function argument to crypto_x25519
X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=5200e8c85c09c36a09b63b4332d37503a143e4b9;p=Monocypher.git

Clarify function argument to crypto_x25519

1. Change param "shared_secret" in crypto_x25519 to "raw_shared_secret"
   to aid quick identification of the difference between it and
   crypto_key_exchange; the "key" vs. "secret" gets lost easily because
   of the shared prefix "shared_".
   This change was traced everywhere in the source code where the old
   name was used as well as the man page.
2. Fix not having punctuation as a separate word in man page macro.
---

diff --git a/man/3monocypher/crypto_key_exchange.3monocypher b/man/3monocypher/crypto_key_exchange.3monocypher
index b10de9e..9a1c9d4 100644
--- a/man/3monocypher/crypto_key_exchange.3monocypher
+++ b/man/3monocypher/crypto_key_exchange.3monocypher
@@ -21,7 +21,7 @@
 .Fc
 .Ft int
 .Fo crypto_x25519
-.Fa "uint8_t shared_secret[32]"
+.Fa "uint8_t raw_shared_secret[32]"
 .Fa "const uint8_t your_secret_key[32]"
 .Fa "const uint8_t their_public_key[32]"
 .Fc
@@ -86,7 +86,7 @@ instead.
 This function computes a shared secret with your secret key
 .Fa your_secret_key
 and the other party's public key
-.Fa their_public_key.
+.Fa their_public_key .
 .Sy Warning: the shared secret is not cryptographically random.
 Do not use it directly as a session key.
 You need to hash it first.
diff --git a/src/monocypher.c b/src/monocypher.c
index 85a6631..aaf2b00 100644
--- a/src/monocypher.c
+++ b/src/monocypher.c
@@ -1235,9 +1235,9 @@ static void x25519_ladder(const fe x1, fe x2, fe z2, fe x3, fe z3,
     fe_cswap(z2, z3, swap);
 }
 
-int crypto_x25519(u8       shared_secret   [32],
-                  const u8 your_secret_key [32],
-                  const u8 their_public_key[32])
+int crypto_x25519(u8       raw_shared_secret[32],
+                  const u8 your_secret_key  [32],
+                  const u8 their_public_key [32])
 {
     // computes the scalar product
     fe x1;
@@ -1257,11 +1257,11 @@ int crypto_x25519(u8       shared_secret   [32],
     // normalises the coordinates: x == X / Z
     fe_invert(z2, z2);
     fe_mul(x2, x2, z2);
-    fe_tobytes(shared_secret, x2);
+    fe_tobytes(raw_shared_secret, x2);
 
     // Returns -1 if the input is all zero
     // (happens with some malicious public keys)
-    return -1 - crypto_zerocmp(shared_secret, 32);
+    return -1 - crypto_zerocmp(raw_shared_secret, 32);
 }
 
 void crypto_x25519_public_key(u8       public_key[32],
@@ -1575,9 +1575,9 @@ int crypto_key_exchange(u8       shared_key[32],
                         const u8 their_public_key[32])
 {
     static const u8 zero[16] = {0};
-    u8 shared_secret[32];
-    int status = crypto_x25519(shared_secret, your_secret_key, their_public_key);
-    crypto_chacha20_H(shared_key, shared_secret, zero);
+    u8 raw_shared_secret[32];
+    int status = crypto_x25519(raw_shared_secret, your_secret_key, their_public_key);
+    crypto_chacha20_H(shared_key, raw_shared_secret, zero);
     return status;
 }
 
diff --git a/src/monocypher.h b/src/monocypher.h
index 8636bc2..4d6eb66 100644
--- a/src/monocypher.h
+++ b/src/monocypher.h
@@ -116,9 +116,9 @@ void crypto_argon2i(uint8_t       *hash,      uint32_t hash_size,     // >= 4
 ///////////////
 /// X-25519 ///
 ///////////////
-int crypto_x25519(uint8_t       shared_secret   [32],
-                  const uint8_t your_secret_key [32],
-                  const uint8_t their_public_key[32]);
+int crypto_x25519(uint8_t       raw_shared_secret[32],
+                  const uint8_t your_secret_key  [32],
+                  const uint8_t their_public_key [32]);
 
 void crypto_x25519_public_key(uint8_t       public_key[32],
                               const uint8_t secret_key[32]);