Document what you're supposed to do with the SharedSecret

[Gaelan]

I recently implemented (thankfully only for a school project) an E2E chat system that directly took the SharedSecret from x25519-dalek and used it as a (chacha20poly1305) key. I've now come across this SE answer which claims that such a construction is risky, and I should really have some sort of hashing step between the DH exchange and the actual cipher key.

Right, ok, rolled my own crypto and got bitten in the ass. Lesson learned, thank god it wasn't for anything real.

That being said, the docs for SharedSecret currently don't provide any guidance for what one should do with the result. In the spirit of building misuse-resistant tools, it'd be great if there was a little more detail in the docs about what properties it's expected to have, and what it is and isn't safe to be used for.

[tarcieri]

NaCl's scalarmult applies HSalsa20 to the output (though HChaCha20 would work just as well).

In the @RustCrypto elliptic-curve crate we provide a SharedSecret::extract method which calls HKDF for you. It also has a fairly prominent warning on the API which provides access to the raw shared secret.