Add examples in doctests for ring::aead API

[briansmith]

The AEAD API is one of the few that doesn't have example code. Let's add the example code, in a similar style as the existing examples for other features.

We're likely to remove the in_prefix_len parameter, so if we only have resources to write two examples, one with in_prefix_len zero and one where it is non-zero, it's best to write one where in_prefix_len is zero.

A good example would be TLS records, which have a 5 byte AAD prefix of { type: u8, ProtocolVersion: u16, length: u16 }.

It would also be good to have an example where there's no ciphertext, and there's only AAD.

[Philipp91]

Proper nonce generation should be explained somewhere. Especially if random nonces aren't secure, as that would be surprising to most users.

[briansmith]

[wrongly-added comment removed]

[Philipp91]

Are you sure you closed the right issue?

[briansmith]

Thanks @Philipp91. Reopened.

[dsprenkels]

If possible, I would like to take this issue. 😄

[briansmith]

My understanding is that there is at least one PR and maybe two different PRs that attempt to fix this issue. Additionally, there are some other patches that completely change the API. So basically I need to decide which direction to go. I imagine I'll just replace the API with a better one. I'll be discussing this with some users of the API soon and I'll update this issue when I've made a decision.

[dsprenkels]

Ok. Thanks for your quick reply! Do you have any good suggestions on which issues are ready to be tackled by a beginner like me?

[briansmith]

See #805 where the beginning of the refactoring of the AEAD API has started. Feedback appreciated.

[artosan]

Any news on this issue? I am having problems using the AEAD API and it would be super nice to have some working examples which show correct nonce use and so on.

[ghost]

Any update?

[ghost]

Btw i found this
https://gist.github.com/jaysonsantos/117c1f7623a2fb2c39e47f6cf87860a3
but it's outdated

[rsdy]

FWIW, zerostash uses the AEAD API from ring, although the nonces are not following standard practice.

[ghost]

I'm playing around with the AEAD's API and created this
https://github.com/briansmith/ring/compare/master...xliiv:aead-example?expand=1

It's a meaningless example, but maybe it helps someone.

[ghost]

Another example could be found in Elichai's Lorenz project
https://github.com/elichai/Lorenz/blob/13032dc8a9cdacbf767008aaa506b07c02007c81/src/encryption.rs#L14-L46

Actually I just finished my example because Elichai pointed me out the link above and gave some hints.