Improve the man page for crypto_key_exchange

1. Improve wording in the section on public keys that yield an all-zero
   result.
2. Fix casing (HCHacha20 -> HChacha20).
3. Resolve contraction to keep the manual style.
4. Add example for key generation and key exchange.  It's not quite
   obvious that you just use straight random bytes.  If coming from
   other X25519 implementations, it may be a surprise not having to
   trim the key.  If coming from other public key cryptographic systems,
   it may be a surprise that key generation is this straightforward.

diff --git a/man/3monocypher/crypto_key_exchange.3monocypher b/man/3monocypher/crypto_key_exchange.3monocypher
index 9a1c9d474d23c7df3cad36bab6651c9adcd91607..09eed6ea4e0c5f5322510f94906d125049a1956a 100644 (file)
--- a/man/3monocypher/crypto_key_exchange.3monocypher
+++ b/man/3monocypher/crypto_key_exchange.3monocypher
@@ -102,19 +102,42 @@ The
 and
 .Fn crypto_x25519
 functions return zero on success.
-The return value serves as a security check: there are a couple evil
-public keys out there, that force the shared key to a known constant
-(the HCHacha20 of zero in the case of
+The return value serves as a security check: there are public keys that
+force the shared key to a known constant (the HChacha20 of zero in the
+case of
 .Fn crypto_key_exchange
 or all-zero in the case of
 .Fn crypto_x25519 ) .
 This never happens with legitimate public keys, but if the ones you
-process aren't known to be trustworthy, check the return value.
+process are not known to be trustworthy, check the return value.
 .Pp
 The
 .Fn crypto_x25519_public_key
 function returns nothing.
 It cannot fail.
+.Sh EXAMPLES
+This example outlines how to generate a private key and a public key,
+then perform a key exchange.
+.Bd -literal -offset indent
+uint8_t sk[32], pk[32];
+uint8_t theirpk[32];
+uint8_t shared_key[32];
+
+/* ...randomly generate sk here... */
+crypto_x25519_public_key(pk, sk);
+
+/* ...read their public key... */
+
+if (crypto_key_exchange(shared_key, sk, theirpk) != 0) {
+        /* ...handle weak key (see RETURN VALUES)...
+         * You probably want to stop processing now.
+         */
+}
+
+/* shared_key can now be used as key, for example in
+ * crypto_lock/crypto_unlock.
+ */
+.Ed
 .Sh SEE ALSO
 .Xr crypto_lock 3monocypher ,
 .Xr intro 3monocypher