Deprecate return values in crypto_x25519

This addresses #102.

This also adds a note that the public key function returns nothing, as
is noted on crypto_key_exchange(3monocypher).

diff --git a/doc/man/man3/crypto_x25519.3monocypher b/doc/man/man3/crypto_x25519.3monocypher
index 7d70af642c2b312c6260f055b06af8048ee2520d..5b0f581ce998b054662a40066566148c4aa6e8b6 100644 (file)
--- a/doc/man/man3/crypto_x25519.3monocypher
+++ b/doc/man/man3/crypto_x25519.3monocypher
@@ -1,4 +1,4 @@
-.Dd December 28, 2017
+.Dd July 18, 2018
 .Dt CRYPTO_X25519 3MONOCYPHER
 .Os
 .Sh NAME
@@ -59,8 +59,23 @@ The public key of the other party.
 Some public keys force the shared key to a known constant.
 This function returns -1 if it detects such a public key, otherwise it
 returns 0.
-This never happens with legitimate public keys, but if the ones you
-process are not known to be trustworthy, check the return value.
+This never happens with legitimate public keys.
+.Pp
+.Sy The return value has been deprecated .
+.Fn crypto_x25519
+will return
+.Vt void
+starting with the next major release of Monocypher.
+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.
+.Pp
+.Fn crypto_x25519_public_key
+returns nothing.
 .Sh EXAMPLES
 Generate a pair of shared keys with your secret key and their public
 key.