From 12ec4a42170508ba0b363fba545531eec029c4d7 Mon Sep 17 00:00:00 2001
From: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date: Tue, 24 Mar 2020 08:41:48 +0100
Subject: [PATCH] doc: contributory behavior may be required sometimes

While already there, hoist the explanation about contributory behavior
from RETURN VALUES to the main DESCRIPTION section.
The only reason it was in RETURN VALUES is because of historical
reasons; we used to justify why the return value was deprecated there,
so the position of the explanation made sense before removal of the
return value.
---
 doc/man/man3/crypto_key_exchange.3monocypher | 10 ++++-----
 doc/man/man3/crypto_x25519.3monocypher       | 22 +++++++++++++-------
 2 files changed, 19 insertions(+), 13 deletions(-)

diff --git a/doc/man/man3/crypto_key_exchange.3monocypher b/doc/man/man3/crypto_key_exchange.3monocypher
index 3134306..c2d0b40 100644
--- a/doc/man/man3/crypto_key_exchange.3monocypher
+++ b/doc/man/man3/crypto_key_exchange.3monocypher
@@ -108,11 +108,6 @@ with
 and
 .Fa your_secret_key
 may overlap if the secret is no longer required.
-.Sh RETURN VALUES
-.Fn crypto_key_exchange
-and
-.Fn crypto_key_exchange_public_key
-return nothing.
 .Pp
 Some poorly designed protocols require to test for
 .Dq contributory
@@ -121,6 +116,11 @@ secret to a known constant.
 Protocols should instead be designed in such a way that no such check
 is necessary, namely by authenticating the other party or exchanging
 keys over a trusted channel.
+.Sh RETURN VALUES
+.Fn crypto_key_exchange
+and
+.Fn crypto_key_exchange_public_key
+return nothing.
 .Sh EXAMPLES
 The following examples assume the existence of
 .Fn arc4random_buf ,
diff --git a/doc/man/man3/crypto_x25519.3monocypher b/doc/man/man3/crypto_x25519.3monocypher
index bc0a159..0aa8b45 100644
--- a/doc/man/man3/crypto_x25519.3monocypher
+++ b/doc/man/man3/crypto_x25519.3monocypher
@@ -114,19 +114,25 @@ and
 .Fa your_secret_key
 may overlap if your secret is no longer required.
 .El
+.Pp
+Some protocols,
+such as some password-authenticated key exchange (PAKE) protocols
+and oblivious pseudo-random functions (OPRF),
+may require
+.Dq contributory
+behaviour, which ensures that no untrusted party forces the shared
+secret to a known constant.
+If a protocol requires contributory behaviour,
+compare the output of
+.Fn crypto_x25519
+to an all-zero buffer using
+.Xr crypto_verify32 3monocypher ;
+abort the protocol if the output and the all-zero buffer are equal.
 .Sh RETURN VALUES
 .Fn crypto_x25519
 and
 .Fn crypto_x25519_public_key
 return nothing.
-.Pp
-Some poorly designed protocols require to test for
-.Dq contributory
-behaviour, which ensures that no untrusted party forces the shared
-secret to a known constant.
-Protocols should instead be designed in such a way that no such check
-is necessary, namely by authenticating the other party or exchanging
-keys over a trusted channel.
 .Sh EXAMPLES
 The following example assumes the existence of
 .Fn arc4random_buf ,
-- 
2.47.3