authorgravatar for 124872+jedisct1@users.noreply.github.comFrank Denis <124872+jedisct1@users.noreply.github.com> 2020-09-23 21:37:16+02:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2020-09-24 00:02:31-04:00
logc8cd6145ac2475e298a3d3b2082e1966fda811d5
treec5800c01e99fdd4e6ee58969934655d4a544139d
parent72f4cdb2b4221658b4c85b33394377081ffae6bb

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.

1 files changed, 17 insertions(+), 6 deletions(-)

lib/std/crypto.zig+17-6
...@@ -35,12 +35,23 @@ pub const onetimeauth = struct {...@@ -35,12 +35,23 @@ pub const onetimeauth = struct {
35 pub const Poly1305 = @import("crypto/poly1305.zig").Poly1305;35 pub const Poly1305 = @import("crypto/poly1305.zig").Poly1305;
36};36};
3737
38/// A Key Derivation Function (KDF) is intended to turn a weak, human generated password into a38/// A password hashing function derives a uniform key from low-entropy input material such as passwords.
39/// strong key, suitable for cryptographic uses. It does this by salting and stretching the39/// It is intentionally slow or expensive.
40/// password. Salting injects non-secret random data, so that identical passwords will be converted40///
41/// into unique keys. Stretching applies a deliberately slow hashing function to frustrate41/// With the standard definition of a key derivation function, if a key space is small, an exhaustive search may be practical.
42/// brute-force guessing.42/// 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:
43pub const kdf = struct {43///
44/// - Requiring a lot of computation cycles to complete
45/// - Requiring a lot of memory to complete
46/// - Requiring multiple CPU cores to complete
47/// - Requiring cache-local data to complete in reasonable time
48/// - Requiring large static tables
49/// - Avoiding precomputations and time/memory tradeoffs
50/// - Requiring multi-party computations
51/// - Combining the input material with random per-entry data (salts), application-specific contexts and keys
52///
53/// Password hashing functions must be used whenever sensitive data has to be directly derived from a password.
54pub const pwhash = struct {
44 pub const pbkdf2 = @import("crypto/pbkdf2.zig").pbkdf2;55 pub const pbkdf2 = @import("crypto/pbkdf2.zig").pbkdf2;
45};56};
4657