From 0e8f0208a758564500170a68ab3f60f8ae010e2d Mon Sep 17 00:00:00 2001
From: CuleX <cculex@gmail.com>
Date: Sat, 9 Sep 2017 13:09:46 +0200
Subject: [PATCH] Improve the crypto_sign man page

1. Reorder the arguments so that crypto_sign_public_key() comes directly
   after crypto_sign().  This harmonizes the order of the public key
   generation functions with crypto_key_exchange(3monocypher).
2. Move implementation details and complaints about SHA-512 to the
   IMPLEMENTATION DETAILS section.
3. Note that there is no incremental interface available in the
   DESCRIPTION and explain it in the IMPLEMENTATION DETAILS section.
4. Add an example for key generation.  Key generation using straight
   random bytes may come as a surprise to people not used working with
   Curve25519.
---
 man/3monocypher/crypto_sign.3monocypher | 64 ++++++++++++++++---------
 1 file changed, 42 insertions(+), 22 deletions(-)

diff --git a/man/3monocypher/crypto_sign.3monocypher b/man/3monocypher/crypto_sign.3monocypher
index ee76e63..93351b5 100644
--- a/man/3monocypher/crypto_sign.3monocypher
+++ b/man/3monocypher/crypto_sign.3monocypher
@@ -16,6 +16,11 @@
 .Fa "const uint8_t *message"
 .Fa "size_t message_size"
 .Fc
+.Ft void
+.Fo crypto_sign_public_key
+.Fa "uint8_t public_key[32]"
+.Fa "const uint8_t secret_key[32]"
+.Fc
 .Ft int
 .Fo crypto_check
 .Fa "const uint8_t signature[64]"
@@ -23,11 +28,6 @@
 .Fa "const uint8_t *message"
 .Fa "size_t message_size"
 .Fc
-.Ft void
-.Fo crypto_sign_public_key
-.Fa "uint8_t public_key[32]"
-.Fa "const uint8_t secret_key[32]"
-.Fc
 .Sh DESCRIPTION
 Authenticated encryption with key exchange is not always enough.
 Sometimes, you want to
@@ -42,21 +42,6 @@ Obviously, any attacker that gets a hold of your private key can sign
 messages in your stead.
 Protect your private key.
 .Pp
-These functions provide public key signatures with a variant of ed25519,
-which uses Blake2b as the hash instead of SHA-512.
-SHA-512 is provided as an option for compatibility with other systems.
-.Pp
-Blake2b is the default because it is faster, more flexible, harder to
-misuse than SHA-512, and already required by
-.Xr crypto_argon2i 3monocypher .
-Monocypher needs only one hash, and that shall be Blake2b.
-.Pp
-Note that using Blake2b instead of SHA-512 does
-.Em not
-block your upgrade path to faster implementations: Floodyberry's Donna
-(ed25519-donna) library provides blazing fast implementations that can
-work with custom hashes.
-.Pp
 The keys used for these functions are
 .Em not
 the same as used for
@@ -96,6 +81,12 @@ If you want to ascertain the origin of a secret message, you may want
 to use the
 .Xr crypto_key_exchange 3monocypher
 function instead.
+.Pp
+An incremental interface is not available.
+If you require an incremental interface, signing a hash of your data
+is an acceptable substitute; see
+.Xr crypto_blake2b_init 3monocypher
+for details about incrementally hashing data.
 .Sh RETURN VALUES
 The
 .Fn crypto_sign_public_key
@@ -107,14 +98,43 @@ They cannot fail.
 The
 .Fn crypto_check
 function returns zero for legitimate messages and -1 for forgeries.
+.Sh EXAMPLES
+This example shows how to generate a private key and a public key.
+.Bd -literal -offset indent
+uint8_t sk[32], pk[32];
+
+/* ...randomly generate sk here... */
+crypto_sign_public_key(pk, sk);
+.Ed
 .Sh SEE ALSO
 .Xr crypto_blake2b 3monocypher ,
 .Xr crypto_key_exchange 3monocypher ,
 .Xr crypto_lock 3monocypher ,
 .Xr intro 3monocypher
 .Sh IMPLEMENTATION DETAILS
-These functions implement edDSA with Curve25519 and Blake2b (or
-optionally SHA-512).
+These functions provide public key signatures with a variant of Ed25519,
+which uses Blake2b as the hash instead of SHA-512.
+SHA-512 is provided as an option for compatibility with other systems.
+.Pp
+Blake2b is the default because it is faster, more flexible, harder to
+misuse than SHA-512, and already required by
+.Xr crypto_argon2i 3monocypher .
+Monocypher needs only one hash function, and that shall be Blake2b.
+.Pp
+Note that using Blake2b instead of SHA-512 does
+.Em not
+block your upgrade path to faster implementations: Floodyberry's Donna
+(ed25519-donna) library provides blazing fast implementations that can
+work with custom hashes.
 .Pp
 The reason why there is a SHA-512 option at all is due to official test
 vectors.
+.Pp
+There is no incremental interface because EdDSA requires the full
+message to be hashed twice in a way that makes parallel hashing
+impossible.
+Workarounds for providing an incremental interface would involve
+lowering the security guarantees of the underlying hash function or
+would introduce grave potential for misuse, likely leading to situations
+such as the Sony PlayStation EdDSA nonce randomization failure.
+For this reason, an incremental interface has not been provided.
-- 
2.47.3