From 69727d5bf1b775c7ace06d11321adab7707fcd22 Mon Sep 17 00:00:00 2001
From: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date: Wed, 18 Jul 2018 16:43:23 +0200
Subject: [PATCH] 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).
---
 doc/man/man3/crypto_x25519.3monocypher | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/doc/man/man3/crypto_x25519.3monocypher b/doc/man/man3/crypto_x25519.3monocypher
index 7d70af6..5b0f581 100644
--- 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.
-- 
2.47.3