LoupVaillant
commented
4 years ago That patch is perfect, thanks a lot.
Your security considerations section works for me. It succinctly explains why you don't want to use a regular hash for handling passwords, and is short enough that it doesn't get in the way. I say we keep it.
@aggsol, I disagree however with expanding hash uses (and non uses) any further. Going through examples would mainly make the manual more cumbersome. And as much as it sucks, those man pages are a reference manual. They can teach you how to use Monocypher, but they are not intended to teach applied cryptography. Users are supposed to have some basic understanding before they can even hope to safely use any cryptographic library of any kind.
We may someday write an applied cryptography tutorial, focused on using modern crypto libraries such as Monocypher or Libsodium. That will be a separate project.
aggsol
Prompted by an inquiry in #154.
The manual work this time is unusually deliberate in multiple ways.
BLAKE2b/SHA-512: The wording "BLAKE2b itself is not suitable" is a compromise between saying "BLAKE2b is not suitable" (which is an assertion I'm not comfortable making while PBKDF2 is still a thing that exists and can work with BLAKE2b as well as anything else—though one may certainly argue how appropriate PBKDF2 still is in times we bicker about Argon2 not having cache resistance) and "BLAKE2b by itself is not suitable" (which would correctly imply there are constructions that may be suitable, but then the question becomes "Why doesn't Monocypher just do this?", and that's one that would go far beyond what the manual is supposed to answer). I'm still not 100% happy with the wording I chose here, but it's an inconvenient tightrope either way.
Security considerations: I did pick up your idea from #154 to have a "Security Considerations" section, but I'm also okay with it being removed. You can't really talk about the issue at length because doing so would end up reinventing applied cryptography books while ultimately not providing much for the actual usage of the functions. While the SHA-512 page mostly refers to the BLAKE2b page, I've intentionally mirrored the "Security Considerations" section here in case people only selectively read the BLAKE2b page.
Intro: Mention password hashing right next to password key derivation. This should help prevent confusion about whether you want a "hash" function or a "password key derivation" function for passwords; the answer is always the latter. This slightly stretches the meaning of the original wording to go beyond what used to be since the relationship between password key derivation and password hashing is a non-trivial one, but this change helps the uninitiated and does no harm for the experienced reader. This may need a corresponding change in the sidebar of the manual on the website.
Authorship notices and mdoc dates bumped as required.