Add an example of using AEAD

[MaxGabriel]

This PR adds example usage of using AEAD to encrypt data. I think this specific functionality is especially worth documenting as @vincenthz recommended packages like clientsession use it. Also, it seems preferable to encourage AEAD rather than e.g. raw AES CTR, where a user might not add a MAC in places they should, or could MAC in an insecure way.

The example code is a longer than I'd like, but the extra space spent on e.g. newtypes makes me more comfortable with a random user coming along and copy/pasting this into their codebase.

This being example code, having the most generally applicable code is probably important. If you think there are better choices than AES256/OCB mode in terms of speed/security/legal tradeoffs, that could be changed. I'm slightly unclear on the OCB patents—it seems like it's fine for e.g. a commercial webapp to use it, as long as it's not on behalf of a military?

The example code is hidden in a collapsible section to keep the docs looking clean:

Rendered:

[ocheron]

Adding documentation here or in Crypto.Tutorial is certainly useful.

I see some possible simplifications:

• coerce should be removed
• AES256Key should not have instances Semigroup, Monoid, ByteArray as we want 32-byte length only
• the IV newtype is not needed as there is already a data type for this in the library
• I don't understand the type parameter on EncryptedDataPackage
• EncryptedData is used only for EncryptedDataPackage so both could be merged

[crockeea]

@MaxGabriel Are you willing to make the requested changes so this can be merged? If not, I can do it.

[MaxGabriel]

@crockeea It would be great if you could take it, thanks!

[vincenthz]

archiving repository