I've just pushed some documentation for the curve25519 and eddsa functions. This raises a few questions on the current interfaces.
1. Should ecc-curves.h really declare nettle_curve25519? Its' not needed for any of the documented functions, except for obscurities like doing ecdsa (not eddsa) over the curve. It could be moved to ecc-internal, or be marked as internal in some other way. Perhaps renaming to _nettle_ed25519 would be appropriate.
2. curve25519_mul should be changed to have a void return type (an earlier implementation failed for inputs which didn't correspond to points on the curve, but instead were points on its twist). But the current implementation, using the Montgomery ladder, doesn't care and computes a well defined result for all inputs.
3. struct ed25519_private_key and struct ed25519_public_key include compile-time constant limb arrays. At least for the public key, this will imply an ABI break if/when we switch to a base 2^51 representations for GF(2^255 - 19). So maybe switch to dynamic allocation for struct ed25519_public_key, or both structs?
4. There's no function to generate eddsa key pairs. To generate a private key, use a random 32-octet string. To get the corresponding public key, one can call ed25519_set_private_key, and copy the pub element of the struct. This needs some additional documentation or maybe some additional function.
Regards, /Niels