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.

diff --git a/doc/man/man3/crypto_key_exchange.3monocypher b/doc/man/man3/crypto_key_exchange.3monocypher
index 31343062692959055d7b123934f7835584ab5fd1..c2d0b404bd0242a4cb3f717935697fa65dfd7102 100644 (file)
--- 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 bc0a159c85d2a64dabe8b07153bc91c90eb0891a..0aa8b459e95cb3ecb0289823443ad8acc368d4dd 100644 (file)
--- 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 ,