While the basic variants are a bit more convenient to use, I don't
expect users will be using them frequently enough for it to matter. But
having 6 functions to chose from instead of 3 is in my opinion a
non-negligible cost.
Then there's HChacha20, the odd one out. While we're here breaking the
API left and right, I figured I needed a stable naming scheme for
everything. And I think each function should be named
crypto_<cluster>_<function_name>(), with relatively few clusters. And
HChacha20 quite clearly belong to the "chacha20" cluster, even though
it's sometimes used as kind of a hash (for the extended nonce DJB only
relies on its properties as a bastardised stream cipher).
And while we're speaking clusters, I'm considering having one man page
per cluster, with no regards towards whether a function is "advanced" or
not. In practice this would mean:
- Bundling HChacha20 and Chacha20 functions in the same man page. This
would help highlight how they're related.
- Bundling low-level EdDSA building blocks with the high-level
construction. We can always push the advanced stuff down the man
page, but the main point here is to make it easier to find. Oh and
we'd perhaps add the conversion to X25519 as well.
- Bundling dirty X25519 function together with the clean one. And
perhaps the conversion to EdDSA too.
- The Elligator functions are already documented together, but I think
they deserve their dedicated prefix. Like, "crypto_elligator_".
However we go about it, I'd like to strive towards a more systematic way
of documenting things, to the point of enabling some automatic checks as
hinted in #250.