I'm currently rethinking the AEAD API as a whole, and to be honest I'm
so happy with this streaming API that I believe it could replace the
regular API entirely.
One problem with the AEAD API is the sheer number of arguments.
`crypto_lock_aead()` and `crypto_unlock_aead()` currently have 8
arguments, comprising 6 pointers (all of the same type) and 2 sizes.
There are way too many opportunities to swap arguments and break stuff.
The streaming API however is divided into an init phase, which has only
3 arguments, and a read/write phase, which has 7, but "only" 4 pointers
to byte buffers. Which I don't think we can improve much. We could try
and use a second struct similar to what we do with Argon2, but with only
7 arguments (compared to Argon2's 15) I don't think we would gain that
much readability.
As for how to use the streaming API for single shot uses, that's obvious
enough:
- Declare the context and call Init.
- Call read/write.
- Wipe the context.
One may argue that everything else (Poly1305, Blake2b, SHA-512, and
HMAC) provide a one-shot API, and we should do so here as well. There's
just one problem: we don't have one init function, we have _three_.
If we provide a one-shot API, orthogonality would need all 3 variants.
That's 6 functions total (3 locks, 3 unlocks), which is a bit much,
especially since at least one of them is only provided for compatibility
with a standard I don't entirely agree with. We could of course only
provide only the single one-shot API (like we do right now), but that
leaves such an obvious hole in the API.
Stopping at just the 5 functions we need for everything (streaming,
one-shot, all 3 variants) is very tempting.