zig

commit c8cd6145ac2475e298a3d3b2082e1966fda811d5 (tree)
parent 72f4cdb2b4221658b4c85b33394377081ffae6bb
Author: Frank Denis <github@pureftpd.org>
Date:   Wed, 23 Sep 2020 21:37:16 +0200

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.

Diffstat:
M
lib/std/crypto.zig
 | 
23
+++++++++++++++++------

1 file changed, 17 insertions(+), 6 deletions(-)
diff --git a/lib/std/crypto.zig b/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;
 };