Documentation/security/siphash.rst

2 SipHash - a short input PRF
7 SipHash is a cryptographically secure PRF -- a keyed hash function -- that
9 cryptographers Daniel J. Bernstein and Jean-Philippe Aumasson. It is intended
14 an input buffer or several input integers. It spits out an integer that is
29 Using the functions
49 will constant fold at compile-time and automatically choose one of the
50 optimized functions.
61 		get_random_bytes(&table->key, sizeof(table->key));
66 …return &table->hashtable[siphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable…
74 SipHash has a very high security margin, with its 128-bit key. So long as the
79 Linux implements the "2-4" variant of SipHash.
81 Struct-passing Pitfalls
84 Often times the XuY functions will not be large enough, and instead you'll
85 want to pass a pre-filled struct to siphash. When doing this, it's important
109 -------------------------------------------------------------------------------
112 HalfSipHash - SipHash's insecure younger cousin
117 On the off-chance that SipHash is not fast enough for your needs, you might be
119 possibility. HalfSipHash cuts SipHash's rounds down from "2-4" to "1-3" and,
120 even scarier, uses an easily brute-forcable 64-bit key (with a 32-bit output)
121 instead of SipHash's 128-bit key. However, this may appeal to some
122 high-performance `jhash` users.
124 HalfSipHash support is provided through the "hsiphash" family of functions.
127    Do not ever use the hsiphash functions except for as a hashtable key
129    will never be transmitted out of the kernel. This is only remotely useful
133 On 64-bit kernels, the hsiphash functions actually implement SipHash-1-3, a
134 reduced-round variant of SipHash, instead of HalfSipHash-1-3. This is because in
135 64-bit code, SipHash-1-3 is no slower than HalfSipHash-1-3, and can be faster.
136 Note, this does *not* mean that in 64-bit kernels the hsiphash functions are the
137 same as the siphash ones, or that they are secure; the hsiphash functions still
138 use a less secure reduced-round algorithm and truncate their outputs to 32
152 Using the hsiphash functions
168 will constant fold at compile-time and automatically choose one of the
169 optimized functions.
183 		get_random_bytes(&table->key, sizeof(table->key));
188 …return &table->hashtable[hsiphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtabl…