authorgravatar for 124872+jedisct1@users.noreply.github.comFrank Denis <124872+jedisct1@users.noreply.github.com> 2020-08-22 14:24:35+02:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2020-08-22 15:12:54-04:00
log2d402157d9e6ea34499604455cf1270ef7eb5a1f
tree5c301cc30417ba197029a572cdd706df32aff536
parentf540dc1b7ebc1663ef5d3823da4630ff51c697b6

Improve documentation on siphash recommended parameters

1 files changed, 7 insertions(+), 2 deletions(-)

lib/std/crypto/siphash.zig+7-2
...@@ -20,8 +20,10 @@ const mem = std.mem;...@@ -20,8 +20,10 @@ const mem = std.mem;
20/// SipHash function with 64-bit output.20/// SipHash function with 64-bit output.
21///21///
22/// Recommended parameters are:22/// Recommended parameters are:
23/// - (c_rounds=4, d_rounds=8) for conservative security; regular hash functions such as BLAKE2 or BLAKE3 are usually a better alternative.
23/// - (c_rounds=2, d_rounds=4) standard parameters.24/// - (c_rounds=2, d_rounds=4) standard parameters.
24/// - (c_rounds=1, d_rounds=2) reduced-round function. Faster, no known implications on its practical security level.25/// - (c_rounds=1, d_rounds=3) reduced-round function. Faster, no known implications on its practical security level.
26/// - (c_rounds=1, d_rounds=2) fastest option, but the output may be distinguishable from random data with related keys or non-uniform input - not suitable as a PRF.
25///27///
26/// SipHash is not a traditional hash function. If the input includes untrusted content, a secret key is absolutely necessary.28/// SipHash is not a traditional hash function. If the input includes untrusted content, a secret key is absolutely necessary.
27/// And due to its small output size, collisions in SipHash64 can be found with an exhaustive search.29/// And due to its small output size, collisions in SipHash64 can be found with an exhaustive search.
...@@ -32,8 +34,11 @@ pub fn SipHash64(comptime c_rounds: usize, comptime d_rounds: usize) type {...@@ -32,8 +34,11 @@ pub fn SipHash64(comptime c_rounds: usize, comptime d_rounds: usize) type {
32/// SipHash function with 128-bit output.34/// SipHash function with 128-bit output.
33///35///
34/// Recommended parameters are:36/// Recommended parameters are:
37/// - (c_rounds=4, d_rounds=8) for conservative security; regular hash functions such as BLAKE2 or BLAKE3 are usually a better alternative.
35/// - (c_rounds=2, d_rounds=4) standard parameters.38/// - (c_rounds=2, d_rounds=4) standard parameters.
36/// - (c_rounds=1, d_rounds=2) reduced-round function. Faster, no known implications on its practical security level.39/// - (c_rounds=1, d_rounds=4) reduced-round function. Recommended to hash very short, similar strings, when a 128-bit PRF output is still required.
40/// - (c_rounds=1, d_rounds=3) reduced-round function. Faster, no known implications on its practical security level.
41/// - (c_rounds=1, d_rounds=2) fastest option, but the output may be distinguishable from random data with related keys or non-uniform input - not suitable as a PRF.
37///42///
38/// SipHash is not a traditional hash function. If the input includes untrusted content, a secret key is absolutely necessary.43/// SipHash is not a traditional hash function. If the input includes untrusted content, a secret key is absolutely necessary.
39pub fn SipHash128(comptime c_rounds: usize, comptime d_rounds: usize) type {44pub fn SipHash128(comptime c_rounds: usize, comptime d_rounds: usize) type {