doc: Mention hashing the public keys (#232)

Mention hashing the public keys

Closes #230.

diff --git a/doc/man/man3/crypto_key_exchange.3monocypher b/doc/man/man3/crypto_key_exchange.3monocypher
index d87f4f178f51afae688230ef4e2a838856795764..78e89551d1de4410ef31e1c0f7c4e2734c17f42a 100644 (file)
--- a/doc/man/man3/crypto_key_exchange.3monocypher
+++ b/doc/man/man3/crypto_key_exchange.3monocypher
@@ -12,6 +12,7 @@
 .\" Copyright (c) 2017-2018 Michael Savage
 .\" Copyright (c) 2017, 2019-2021 Fabio Scotoni
 .\" Copyright (c) 2020 Richard Walmsley
+.\" Copyright (c) 2022 Samuel Lucas
 .\" All rights reserved.
 .\"
 .\"
@@ -41,8 +42,8 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2017-2021 by Loup Vaillant, Michael Savage, Fabio Scotoni and
-.\" Richard Walmsley
+.\" Written in 2017-2022 by Loup Vaillant, Michael Savage, Fabio Scotoni,
+.\" Richard Walmsley and Samuel Lucas
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -52,7 +53,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd June 11, 2021
+.Dd February 12, 2022
 .Dt CRYPTO_KEY_EXCHANGE 3MONOCYPHER
 .Os
 .Sh NAME
@@ -179,6 +180,16 @@ If either of the long-term secret keys leaks, it may compromise
 .Em all past messages .
 This can be avoided by using protocols that provide forward secrecy,
 such as the X3DH key agreement protocol.
+.Pp
+Many (private, public) key pairs produce the same shared secret.
+Therefore, not including the public keys in the key derivation can
+lead to subtle vulnerabilities.
+This can be avoided by hashing the shared secret concatenated with
+both public keys.
+For example,
+.D1 BLAKE2b(shared_secret || your_pk || their_pk)
+using
+.Xr crypto_blake2b 3monocypher .
 .Sh IMPLEMENTATION DETAILS
 .Fn crypto_key_exchange_public_key
 is an alias to