Move PBKDF2 to a pwhash category, clarify what that category is

Password hashing functions are not general-purpose KDFs, and KDFs
don't have to satisfy the same properties as a PHF.

This will allow fast KDFs such as the HKDF construction to be in a
category of their own, while clarifying what functions are suitable
for using passwords as inputs.

Author: jedisct1

lib/std/crypto.zig

@@ -35,12 +35,23 @@ pub const onetimeauth = struct {
     pub const Poly1305 = @import("crypto/poly1305.zig").Poly1305;
 };
 
-/// A Key Derivation Function (KDF) is intended to turn a weak, human generated password into a
-/// strong key, suitable for cryptographic uses. It does this by salting and stretching the
-/// password. Salting injects non-secret random data, so that identical passwords will be converted
-/// into unique keys. Stretching applies a deliberately slow hashing function to frustrate
-/// brute-force guessing.
-pub const kdf = struct {
+/// A password hashing function derives a uniform key from low-entropy input material such as passwords.
+/// It is intentionally slow or expensive.
+///
+/// With the standard definition of a key derivation function, if a key space is small, an exhaustive search may be practical.
+/// Password hashing functions make exhaustive searches way slower or way more expensive, even when implemented on GPUs and ASICs, by using different, optionally combined strategies:
+///
+/// - Requiring a lot of computation cycles to complete
+/// - Requiring a lot of memory to complete
+/// - Requiring multiple CPU cores to complete
+/// - Requiring cache-local data to complete in reasonable time
+/// - Requiring large static tables
+/// - Avoiding precomputations and time/memory tradeoffs
+/// - Requiring multi-party computations
+/// - Combining the input material with random per-entry data (salts), application-specific contexts and keys
+///
+/// Password hashing functions must be used whenever sensitive data has to be directly derived from a password.
+pub const pwhash = struct {
     pub const pbkdf2 = @import("crypto/pbkdf2.zig").pbkdf2;
 };