Link to recommended high-level crates in rustdoc.

[holly-hacker]

I wanted to encrypt something using AES in my app so I found the aes crate on docs.rs. It mentions the following:

⚠️ Security Warning: Hazmat! This crate implements only the low-level block cipher function, and is intended for use for implementing higher-level constructions only. It is NOT intended for direct use in applications.

USE AT YOUR OWN RISK!

It's good that this warning is here, but it does not point the user to the high-level crate they should use instead. It would be nice if it did, like how the README of this repo does.

[tarcieri]

It seems we have this documented in the README.md but not the rustdoc: https://github.com/RustCrypto/block-ciphers/tree/master/aes#security

In the next release we can use the #![doc = include_str!("../README.md")] trick to consolidate the README.md and the rustdoc, and that should take care of it.

[holly-hacker]

That would work, thank you. In the case of AES, is there a problem with linking to the block-modes repo for usecases that don't require checking the authenticity of the ciphertext? I notice that only AEAD is mentioned, which (to my limited knowledge) is slightly more complex to use than a normal block mode.

[tarcieri]

We should definitely link to the block-modes repo as it's a common source of confusion (possibly linking directly to specific block modes like cbc), but we also need to clearly communicate those modes are unauthenticated and vulnerable to chosen ciphertext attacks