Deprecate crypto_key_exchange

See #230.
In summary:
The way crypto_key_exchange() works was not optimal.
Several combinations of (private, public) key pairs produce the same
shared secret (see 54a7ef551078dda001f94f1045e142af0fc1008a);
crypto_key_exchange() did nothing to mitigate that.

Since this is a high-level function that cannot be saved even with
documentation because it is so fundamentally misguided,
it is now deprecated (see #232).
Users are encouraged to either adopt the function into their own code
if and only if they require it for backwards compatibility,
starting with the release that removes it,
or preferably migrate to implementing an existing protocol,
such as instantiating a Noise protocol pattern or a protocol like X3DH.

diff --git a/doc/man/man3/advanced/crypto_curve_to_hidden.3monocypher b/doc/man/man3/advanced/crypto_curve_to_hidden.3monocypher
index 6063b8e3965c9e08bda9701f5b50728ea5eb4d8c..4c91b68ce3be5f5c71a2fbe4defe85eb171c4767 100644 (file)
--- a/doc/man/man3/advanced/crypto_curve_to_hidden.3monocypher
+++ b/doc/man/man3/advanced/crypto_curve_to_hidden.3monocypher
@@ -8,7 +8,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Copyright (c) 2020 Fabio Scotoni
+.\" Copyright (c) 2020, 2022 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -38,7 +38,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2020 by Fabio Scotoni
+.\" Written in 2020 and 2022 by Fabio Scotoni
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -48,7 +48,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd March 31, 2020
+.Dd February 13, 2022
 .Dt CRYPTO_CURVE_TO_HIDDEN 3MONOCYPHER
 .Os
 .Sh NAME
@@ -91,8 +91,11 @@ This is an
 Unless you are implementing an protocol that requires
 indistinguishability of all communications from random noise,
 consider
-.Xr crypto_key_exchange_public_key 3monocypher
+.Xr crypto_x25519 3monocypher
 instead.
+Both this family of functions and
+.Xr crypto_x25519 3monocypher
+should be used as a building block to implement a key exchange protocol.
 .Pp
 For understanding what these functions do, it is important to note that
 a
@@ -234,12 +237,11 @@ uint8_t their_pk  [32]; /* Their unhidden public key */
 uint8_t your_sk   [32]; /* Your secret key           */
 uint8_t shared_key[32]; /* Shared session key        */
 crypto_hidden_to_curve(their_pk, hidden_pk);
-crypto_key_exchange(shared_key, your_sk, their_pk);
+crypto_x25519(shared_key, your_sk, their_pk);
 /* Wipe secrets if they are no longer needed */
 crypto_wipe(your_sk, 32);
 .Ed
 .Sh SEE ALSO
-.Xr crypto_key_exchange 3monocypher ,
 .Xr crypto_x25519 3monocypher ,
 .Xr crypto_x25519_dirty_small 3monocypher ,
 .Xr intro 3monocypher

diff --git a/doc/man/man3/advanced/crypto_from_eddsa_private.3monocypher b/doc/man/man3/advanced/crypto_from_eddsa_private.3monocypher
index 8781a1043c6dcf088be12600aef41d16339c021a..0c22d65e97f77d2f2b6cdb053b2d8e828499fd72 100644 (file)
--- a/doc/man/man3/advanced/crypto_from_eddsa_private.3monocypher
+++ b/doc/man/man3/advanced/crypto_from_eddsa_private.3monocypher
@@ -8,7 +8,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Copyright (c) 2020 Fabio Scotoni
+.\" Copyright (c) 2020, 2022 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -38,7 +38,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2020 by Fabio Scotoni
+.\" Written in 2020 and 2022 by Fabio Scotoni
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -48,7 +48,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd March 25, 2020
+.Dd February 13, 2022
 .Dt CRYPTO_FROM_EDDSA_PRIVATE 3MONOCYPHER
 .Os
 .Sh NAME
@@ -72,7 +72,7 @@ These functions convert keys for use with
 .Xr crypto_sign 3monocypher
 (EdDSA with the BLAKE2b hash function)
 to keys for use with
-.Xr crypto_key_exchange 3monocypher
+.Xr crypto_x25519 3monocypher
 and
 .Xr crypto_x25519 3monocypher .
 This may be useful in some resource-constrained contexts or when no
@@ -114,7 +114,7 @@ The arguments may overlap or point at the same buffer.
 These functions return nothing.
 They cannot fail.
 .Sh SEE ALSO
-.Xr crypto_key_exchange_public_key 3monocypher ,
+.Xr crypto_x25519 3monocypher ,
 .Xr crypto_sign_public_key 3monocypher ,
 .Xr intro 3monocypher
 .Sh HISTORY

diff --git a/doc/man/man3/advanced/crypto_hchacha20.3monocypher b/doc/man/man3/advanced/crypto_hchacha20.3monocypher
index 1411c28d39490de7861aafb8bb0525e12d772c84..58cb86ab5372e568e8c6116dc7e9cadf42bfbfc8 100644 (file)
--- a/doc/man/man3/advanced/crypto_hchacha20.3monocypher
+++ b/doc/man/man3/advanced/crypto_hchacha20.3monocypher
@@ -10,7 +10,7 @@
 .\"
 .\" Copyright (c) 2017-2019 Loup Vaillant
 .\" Copyright (c) 2017-2018 Michael Savage
-.\" Copyright (c) 2019-2021 Fabio Scotoni
+.\" Copyright (c) 2019-2022 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -40,7 +40,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2017-2021 by Loup Vaillant, Michael Savage and Fabio Scotoni
+.\" Written in 2017-2022 by Loup Vaillant, Michael Savage and Fabio Scotoni
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -50,7 +50,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd June 11, 2021
+.Dd February 13, 2022
 .Dt CRYPTO_HCHACHA20 3MONOCYPHER
 .Os
 .Sh NAME
@@ -114,7 +114,6 @@ crypto_wipe(in , 16);
 .Ed
 .Sh SEE ALSO
 .Xr crypto_chacha20_encrypt 3monocypher ,
-.Xr crypto_key_exchange 3monocypher ,
 .Xr intro 3monocypher
 .Sh STANDARDS
 This function implements HChaCha20.

diff --git a/doc/man/man3/advanced/crypto_sign_init_first_pass.3monocypher b/doc/man/man3/advanced/crypto_sign_init_first_pass.3monocypher
index e62d43d6821e3928c8a6f5ae7ca95ba3d4859acd..cbaaf05383a06852b5657a4f5bd7842c7a650f07 100644 (file)
--- a/doc/man/man3/advanced/crypto_sign_init_first_pass.3monocypher
+++ b/doc/man/man3/advanced/crypto_sign_init_first_pass.3monocypher
@@ -10,7 +10,7 @@
 .\"
 .\" Copyright (c) 2017-2021 Loup Vaillant
 .\" Copyright (c) 2017-2018 Michael Savage
-.\" Copyright (c) 2017, 2019-2021 Fabio Scotoni
+.\" Copyright (c) 2017, 2019-2022 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -40,7 +40,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2017-2021 by Loup Vaillant, Michael Savage and Fabio Scotoni
+.\" Written in 2017-2022 by Loup Vaillant, Michael Savage and Fabio Scotoni
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -50,7 +50,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd June 11, 2021
+.Dd February 13, 2022
 .Dt CRYPTO_SIGN_INIT_FIRST_PASS 3MONOCYPHER
 .Os
 .Sh NAME
@@ -258,7 +258,7 @@ crypto_wipe(sk,  32);
 .Ed
 .Sh SEE ALSO
 .Xr crypto_blake2b 3monocypher ,
-.Xr crypto_key_exchange 3monocypher ,
+.Xr crypto_x25519 3monocypher ,
 .Xr crypto_lock 3monocypher ,
 .Xr crypto_sign 3monocypher ,
 .Xr crypto_wipe 3monocypher ,

diff --git a/doc/man/man3/advanced/crypto_x25519_dirty_fast.3monocypher b/doc/man/man3/advanced/crypto_x25519_dirty_fast.3monocypher
index dd444171bb753e1ca8d4729c336d32b6e2689938..2998f64f9e609c8bb0543f73070a478a10c3aa6e 100644 (file)
--- a/doc/man/man3/advanced/crypto_x25519_dirty_fast.3monocypher
+++ b/doc/man/man3/advanced/crypto_x25519_dirty_fast.3monocypher
@@ -8,7 +8,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Copyright (c) 2020 Fabio Scotoni
+.\" Copyright (c) 2020, 2022 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -38,7 +38,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2020 by Fabio Scotoni
+.\" Written in 2020 and 2022 by Fabio Scotoni
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -48,7 +48,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd March 24, 2020
+.Dd February 13, 2022
 .Dt CRYPTO_X25519_DIRTY_FAST 3monocypher
 .Os
 .Sh NAME
@@ -75,8 +75,6 @@ unless you are reading this because you were referred here from
 .Xr crypto_curve_to_hidden 3monocypher ,
 .Sy you likely have no reason to be using these functions
 and are probably looking for
-.Xr crypto_key_exchange 3monocypher
-or
 .Xr crypto_x25519 3monocypher
 instead.
 Expect elliptic curve jargon on this page.
@@ -101,16 +99,13 @@ yields the same result with less code, less memory, and more time than
 .Fn crypto_x25519_dirty_fast .
 .Pp
 The resulting public keys are to be used with
-.Xr crypto_x25519 3monocypher
-or
-.Xr crypto_key_exchange 3monocypher ,
-which clear the cofactor.
+.Xr crypto_x25519 3monocypher ,
+which clears the cofactor.
 .Sh RETURN VALUES
 These functions have no return value.
 They cannot fail.
 .Sh SEE ALSO
 .Xr crypto_curve_to_hidden 3monocypher ,
-.Xr crypto_key_exchange_public_key 3monocypher ,
 .Xr crypto_x25519_public_key 3monocypher ,
 .Xr intro 3monocypher
 .Sh HISTORY

diff --git a/doc/man/man3/advanced/crypto_x25519_inverse.3monocypher b/doc/man/man3/advanced/crypto_x25519_inverse.3monocypher
index dba9df695e39502dffd65867f956c65b8c495cfc..5cb093db5a517617d8f486f92ce94e03d201728b 100644 (file)
--- a/doc/man/man3/advanced/crypto_x25519_inverse.3monocypher
+++ b/doc/man/man3/advanced/crypto_x25519_inverse.3monocypher
@@ -8,7 +8,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Copyright (c) 2020 Fabio Scotoni
+.\" Copyright (c) 2020, 2022 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -38,7 +38,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2020 by Fabio Scotoni
+.\" Written in 2020 and 2022 by Fabio Scotoni
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -48,7 +48,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd March 24, 2020
+.Dd February 13, 2022
 .Dt CRYPTO_X25519_INVERSE 3MONOCYPHER
 .Os
 .Sh NAME
@@ -71,8 +71,6 @@ of a scalar for X25519.
 unless you are implementing a protocol that requires this specifically,
 .Sy you likely have no reason to be using these functions
 and are probably looking for
-.Xr crypto_key_exchange 3monocypher
-or
 .Xr crypto_x25519 3monocypher
 instead.
 Expect elliptic curve jargon on this page.

diff --git a/doc/man/man3/crypto_blake2b.3monocypher b/doc/man/man3/crypto_blake2b.3monocypher
index 6362f2c7262d6899710ce18acda6d2e6cf6d59f1..23f02d150f6b9327b11c9d39fb788ccb8f715d34 100644 (file)
--- a/doc/man/man3/crypto_blake2b.3monocypher
+++ b/doc/man/man3/crypto_blake2b.3monocypher
@@ -10,7 +10,7 @@
 .\"
 .\" Copyright (c) 2017-2019 Loup Vaillant
 .\" Copyright (c) 2018 Michael Savage
-.\" Copyright (c) 2017, 2020-2021 Fabio Scotoni
+.\" Copyright (c) 2017, 2020-2022 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -40,7 +40,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2017-2021 by Loup Vaillant, Michael Savage and Fabio Scotoni
+.\" Written in 2017-2022 by Loup Vaillant, Michael Savage and Fabio Scotoni
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -50,7 +50,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd June 11, 2021
+.Dd February 13, 2022
 .Dt CRYPTO_BLAKE2B 3MONOCYPHER
 .Os
 .Sh NAME
@@ -274,7 +274,7 @@ for (size_t i = 0; i < 500; i += 100) {
 crypto_blake2b_final(&ctx, hash);
 .Ed
 .Sh SEE ALSO
-.Xr crypto_key_exchange 3monocypher ,
+.Xr crypto_x25519 3monocypher ,
 .Xr crypto_lock 3monocypher ,
 .Xr intro 3monocypher
 .Sh STANDARDS

diff --git a/doc/man/man3/crypto_lock.3monocypher b/doc/man/man3/crypto_lock.3monocypher
index 0e3f824a98f32909f90c295fadd560a49f093b40..5d3ce4811ccb6e4c23af79ce45379448e2925769 100644 (file)
--- a/doc/man/man3/crypto_lock.3monocypher
+++ b/doc/man/man3/crypto_lock.3monocypher
@@ -10,7 +10,7 @@
 .\"
 .\" Copyright (c) 2017-2019 Loup Vaillant
 .\" Copyright (c) 2017-2018 Michael Savage
-.\" Copyright (c) 2017, 2019-2021 Fabio Scotoni
+.\" Copyright (c) 2017, 2019-2022 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -40,7 +40,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2017-2021 by Loup Vaillant, Michael Savage and Fabio Scotoni
+.\" Written in 2017-2022 by Loup Vaillant, Michael Savage and Fabio Scotoni
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -50,7 +50,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd June 11, 2021
+.Dd February 13, 2022
 .Dt CRYPTO_LOCK 3MONOCYPHER
 .Os
 .Sh NAME
@@ -117,8 +117,8 @@ password-based key derivation
 (the password must be communicated on a secure channel),
 or even meeting physically.
 See
-.Xr crypto_key_exchange 3monocypher
-for key exchange and
+.Xr crypto_x25519 3monocypher
+for a bulding block for a key exchange protocol and
 .Xr crypto_argon2i 3monocypher
 for password-based key derivation.
 .It Fa nonce
@@ -313,7 +313,7 @@ if (crypto_unlock(text, key, nonce, mac, text, 12)) {
 }
 .Ed
 .Sh SEE ALSO
-.Xr crypto_key_exchange 3monocypher ,
+.Xr crypto_x25519 3monocypher ,
 .Xr crypto_wipe 3monocypher ,
 .Xr intro 3monocypher
 .Sh STANDARDS

diff --git a/doc/man/man3/crypto_sign.3monocypher b/doc/man/man3/crypto_sign.3monocypher
index 5710c279fd494e8c4300961335d9a13767bdc5e5..aa2a6b8e4b01224a3d8419d80ffb641656ad613a 100644 (file)
--- a/doc/man/man3/crypto_sign.3monocypher
+++ b/doc/man/man3/crypto_sign.3monocypher
@@ -10,7 +10,7 @@
 .\"
 .\" Copyright (c) 2017-2019 Loup Vaillant
 .\" Copyright (c) 2017-2018 Michael Savage
-.\" Copyright (c) 2017, 2019-2021 Fabio Scotoni
+.\" Copyright (c) 2017, 2019-2022 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -40,7 +40,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2017-2021 by Loup Vaillant, Michael Savage and Fabio Scotoni
+.\" Written in 2017-2022 by Loup Vaillant, Michael Savage and Fabio Scotoni
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -50,7 +50,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd June 11, 2021
+.Dd February 13, 2022
 .Dt CRYPTO_SIGN 3MONOCYPHER
 .Os
 .Sh NAME
@@ -134,8 +134,9 @@ It does not have to in most threat models because nothing is secret:
 everyone knows the public key, and the signature and message are
 rarely secret.
 If the message needs to be secret, use
-.Xr crypto_key_exchange 3monocypher
-and
+a key exchange protocol involving
+.Xr crypto_x25519 3monocypher
+and then
 .Xr crypto_lock_aead 3monocypher
 instead.
 .Pp
@@ -193,7 +194,7 @@ if (crypto_check(signature, pk, message, 10)) {
 .Ed
 .Sh SEE ALSO
 .Xr crypto_blake2b 3monocypher ,
-.Xr crypto_key_exchange 3monocypher ,
+.Xr crypto_x25519 3monocypher ,
 .Xr crypto_lock 3monocypher ,
 .Xr intro 3monocypher
 .Sh STANDARDS

diff --git a/doc/man/man3/advanced/crypto_x25519.3monocypher b/doc/man/man3/crypto_x25519.3monocypher
similarity index 94%
rename from doc/man/man3/advanced/crypto_x25519.3monocypher
rename to doc/man/man3/crypto_x25519.3monocypher
index bad7b41a85858ec602915decfeb709d0598c35e2..ab4d29ac1063f55c45000b73e2b2a97a53e29be8 100644 (file)
--- a/doc/man/man3/advanced/crypto_x25519.3monocypher
+++ b/doc/man/man3/crypto_x25519.3monocypher
@@ -10,7 +10,7 @@
 .\"
 .\" Copyright (c) 2017-2021 Loup Vaillant
 .\" Copyright (c) 2017-2018 Michael Savage
-.\" Copyright (c) 2017, 2019-2020 Fabio Scotoni
+.\" Copyright (c) 2017, 2019-2020, 2022 Fabio Scotoni
 .\" Copyright (c) 2020 Richard Walmsley
 .\" All rights reserved.
 .\"
@@ -41,7 +41,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2017-2021 by Loup Vaillant, Michael Savage, Fabio Scotoni and
+.\" Written in 2017-2022 by Loup Vaillant, Michael Savage, Fabio Scotoni and
 .\" Richard Walmsley
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
@@ -52,7 +52,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd June 6, 2021
+.Dd February 13, 2022
 .Dt CRYPTO_X25519 3MONOCYPHER
 .Os
 .Sh NAME
@@ -78,15 +78,14 @@ computes a shared secret with
 .Fa your_secret_key
 and
 .Fa their_public_key .
-It is a low-level primitive.
-Use
-.Xr crypto_key_exchange 3monocypher
-unless you have a specific reason not to.
+It is a low-level primitive;
+X25519 is a building block for protocols.
+To perform a key exchange,
+use a higher level protocol,
+such as the X3DH key agreement protocol.
 .Pp
 .Fn crypto_x25519_public_key
-is the same as
-.Xr crypto_key_exchange_public_key 3monocypher .
-It deterministically computes the public key from a random secret key.
+deterministically computes the public key from a random secret key.
 .Pp
 The arguments are:
 .Bl -tag -width Ds
@@ -172,7 +171,6 @@ const uint8_t *key_2 = shared_keys + 32; /* Shared key 2 */
 crypto_wipe(shared_secret, 32);
 .Ed
 .Sh SEE ALSO
-.Xr crypto_key_exchange 3monocypher ,
 .Xr intro 3monocypher
 .Sh STANDARDS
 This function implements X25519, described in RFC 7748.

diff --git a/doc/man/man3/advanced/crypto_x25519_public_key.3monocypher b/doc/man/man3/crypto_x25519_public_key.3monocypher
similarity index 100%
rename from doc/man/man3/advanced/crypto_x25519_public_key.3monocypher
rename to doc/man/man3/crypto_x25519_public_key.3monocypher

diff --git a/doc/man/man3/crypto_key_exchange.3monocypher b/doc/man/man3/deprecated/crypto_key_exchange.3monocypher
similarity index 97%
rename from doc/man/man3/crypto_key_exchange.3monocypher
rename to doc/man/man3/deprecated/crypto_key_exchange.3monocypher
index 78e89551d1de4410ef31e1c0f7c4e2734c17f42a..6f23d955b0bcd898b3b92e41283448d3f4a85a93 100644 (file)
--- a/doc/man/man3/crypto_key_exchange.3monocypher
+++ b/doc/man/man3/deprecated/crypto_key_exchange.3monocypher
@@ -80,6 +80,11 @@ computes a shared key with your secret key and their public key.
 .Fn crypto_key_exchange_public_key
 deterministically computes the public key from a random secret key.
 .Pp
+These functions are
+.Sy deprecated
+in favor of using a higher level protocol with
+.Xr crypto_x25519 3monocypher .
+.Pp
 The arguments are:
 .Bl -tag -width Ds
 .It Fa shared_key
@@ -175,6 +180,8 @@ function first appeared in Monocypher 0.2.
 The
 .Fn crypto_key_exchange_public_key
 macro alias first appeared in Monocypher 1.1.0.
+Both were deprecated in Monocypher 3.1.3
+and are planned to be removed in Monocypher 4.0.0.
 .Sh SECURITY CONSIDERATIONS
 If either of the long-term secret keys leaks, it may compromise
 .Em all past messages .

diff --git a/doc/man/man3/crypto_key_exchange_public_key.3monocypher b/doc/man/man3/deprecated/crypto_key_exchange_public_key.3monocypher
similarity index 100%
rename from doc/man/man3/crypto_key_exchange_public_key.3monocypher
rename to doc/man/man3/deprecated/crypto_key_exchange_public_key.3monocypher

diff --git a/doc/man/man3/intro.3monocypher b/doc/man/man3/intro.3monocypher
index eeefe7e18b5007afad5c8fbec5a0ad236e189738..e6d4d1984f278313917ea216c31b5c0a16e8559c 100644 (file)
--- a/doc/man/man3/intro.3monocypher
+++ b/doc/man/man3/intro.3monocypher
@@ -10,7 +10,7 @@
 .\"
 .\" Copyright (c) 2017-2021 Loup Vaillant
 .\" Copyright (c) 2018 Michael Savage
-.\" Copyright (c) 2017, 2019-2021 Fabio Scotoni
+.\" Copyright (c) 2017, 2019-2022 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -40,7 +40,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2017-2021 by Loup Vaillant, Michael Savage and Fabio Scotoni
+.\" Written in 2017-2022 by Loup Vaillant, Michael Savage and Fabio Scotoni
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -50,7 +50,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd June 11, 2021
+.Dd February 13, 2022
 .Dt INTRO 3MONOCYPHER
 .Os
 .Sh NAME
@@ -96,7 +96,7 @@ from passwords.
 Argon2 won the password hashing competition in 2015.
 Unlike scrypt, Argon2i is immune to timing attacks.
 .Ss Key exchange (Public Key Cryptography)
-.Xr crypto_key_exchange 3monocypher
+.Xr crypto_x25519 3monocypher
 implements X25519, an elliptic curve Diffie Hellman key exchange
 algorithm based on Curve25519.
 X25519 derives a shared secret from two private/public key pairs.
@@ -165,7 +165,6 @@ and
 .Xr crypto_hidden_to_curve 3monocypher ,
 .Xr crypto_ietf_chacha20 3monocypher ,
 .Xr crypto_ietf_chacha20_ctr 3monocypher ,
-.Xr crypto_key_exchange 3monocypher ,
 .Xr crypto_lock 3monocypher ,
 .Xr crypto_lock_aead 3monocypher ,
 .Xr crypto_poly1305 3monocypher ,

diff --git a/doc/man/man3/optional/crypto_ed25519_sign.3monocypher b/doc/man/man3/optional/crypto_ed25519_sign.3monocypher
index c2d6bc86538c5d909c9baf2e7e8003feaa068116..cae71be8e99dfa55369072f793771da87b4bd142 100644 (file)
--- a/doc/man/man3/optional/crypto_ed25519_sign.3monocypher
+++ b/doc/man/man3/optional/crypto_ed25519_sign.3monocypher
@@ -8,7 +8,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Copyright (c) 2019-2020 Fabio Scotoni
+.\" Copyright (c) 2019-2020, 2022 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -38,7 +38,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2019-2020 by Fabio Scotoni
+.\" Written in 2019-2020 and 2022 by Fabio Scotoni
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -48,7 +48,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd May 24, 2020
+.Dd February 13, 2022
 .Dt CRYPTO_ED25519_SIGN 3MONOCYPHER
 .Os
 .Sh NAME
@@ -105,7 +105,7 @@ return nothing.
 returns 0 for legitimate messages and -1 for forgeries.
 .Sh SEE ALSO
 .Xr crypto_check 3monocypher ,
-.Xr crypto_key_exchange 3monocypher ,
+.Xr crypto_x25519 3monocypher ,
 .Xr crypto_lock 3monocypher ,
 .Xr crypto_sha512 3monocypher ,
 .Xr intro 3monocypher

diff --git a/doc/man/man3/optional/crypto_ed25519_sign_init_first_pass.3monocypher b/doc/man/man3/optional/crypto_ed25519_sign_init_first_pass.3monocypher
index 6f4bf030235b944d586f742199e888250f640bac..61fd649df9205f50e2f12bb5091a9f8656d2c09a 100644 (file)
--- a/doc/man/man3/optional/crypto_ed25519_sign_init_first_pass.3monocypher
+++ b/doc/man/man3/optional/crypto_ed25519_sign_init_first_pass.3monocypher
@@ -8,7 +8,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Copyright (c) 2019-2020 Fabio Scotoni
+.\" Copyright (c) 2019-2020, 2022 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -38,7 +38,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .\"
-.\" Written in 2019-2020 by Fabio Scotoni
+.\" Written in 2019-2020 and 2022 by Fabio Scotoni
 .\"
 .\" To the extent possible under law, the author(s) have dedicated all copyright
 .\" and related neighboring rights to this software to the public domain
@@ -48,7 +48,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd May 24,2020
+.Dd February 13, 2022
 .Dt CRYPTO_ED25519_SIGN_INIT_FIRST_PASS 3MONOCYPHER
 .Os
 .Sh NAME
@@ -131,7 +131,7 @@ return nothing.
 returns 0 for legitimate messages and -1 for forgeries.
 .Sh SEE ALSO
 .Xr crypto_blake2b 3monocypher ,
-.Xr crypto_key_exchange 3monocypher ,
+.Xr crypto_x25519 3monocypher ,
 .Xr crypto_lock 3monocypher ,
 .Xr crypto_ed25519_sign 3monocypher ,
 .Xr crypto_sign 3monocypher ,