xsalsa20poly1305: improve usage documentation

[touilleMan]

As a new user of this library, I found surprisingly hard to understand how to use it 🤔

I think the documentation would benefit from providing an example closer to reality, hence I've changed the documentation to generate real key and nonce.

The drawback is this add the rand create to doc-requirements.

I wanted to to a similar change in chacha20poly1305 (considering the two crates should be really similar), but they don't share the same API (at least chacha20poly1305::generate_nonce doesn't exist) is this expected ?

[tarcieri]

Hi there, thanks for contributing!

Indeed providing RNG advice across the many, many crates we maintain has been a bit of an ongoing problem.

In some places we have taken the approach you're suggesting, albeit with rand_core rather than rand. Here are some examples:

• https://docs.rs/crypto_secretstream/0.0.1/crypto_secretstream/#usage
• https://docs.rs/crypto_kx/0.0.1/crypto_kx/#usage
• https://docs.rs/k256/0.9.6/k256/ecdsa/index.html#signingverification-example
• https://docs.rs/p256/0.9.0/p256/ecdsa/index.html#signingverification-example

I'd say this approach has still left people confused with how to import rand_core, and especially confused when we bump versions.

For this reason we began re-exporting rand_core from the trait crates, allowing an all-in-one solution which doesn't require the end user to loop in another dependency, and also ensures the versions match:

RustCrypto/traits#683

I would suggest documenting things in terms of the re-exported rand_core, which for end users ensures versions are in sync and also eliminates the need to have a dev-dependency.

I wanted to to a similar change in chacha20poly1305 (considering the two crates should be really similar), but they don't share the same API (at least chacha20poly1305::generate_nonce doesn't exist) is this expected ?

Yes, while we haven't given great advice about nonces, we've been hesitant to explicitly add a happy path for using random data for 96-bit nonces as used by ChaCha20Poly1305, as this has a birthday bound of 2^48, which while large is still within the realm of possibility in any multi-user scenario. Indeed the XSalsa20Poly1305 nonce is 192-bits to make it safe to use in this capacity.

It would be safe to add such an API for XChaCha20Poly1305.

I would be okay with well-written generally useful documentation about nonce management, but that should probably go in the aead crate, not duplicated across the myriad AEAD crates we maintain, as that becomes a maintenance burden. Some higher-level constructions might also be helpful here, such as an auto-incrementing nonce manager, which we do already provide to some extent via the aead::stream API.

[tarcieri]

This is a nice direction, but the API is changing and this PR is stale.

Please reopen if you'd like to continue it.