iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation: siphash: disambiguate HalfSipHash algorithm from hsiphash functions

Browse Source 
Fix the documentation for the hsiphash functions to avoid conflating the
HalfSipHash algorithm with the hsiphash functions, since these functions
actually implement either HalfSipHash or SipHash, and random.c now uses
HalfSipHash (in a very special way) without the hsiphash functions.

Signed-off-by: Eric Biggers <ebiggers@google.com>
Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
This commit is contained in:
Eric Biggers 2022-04-21 17:27:31 -07:00 committed by Jason A. Donenfeld
parent 2fbfeb4fa6
commit 5a7e470e46
1 changed files with 22 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
Documentation/security/siphash.rst
View File

@ -121,15 +121,25 @@ even scarier, uses an easily brute-forcable 64-bit key (with a 32-bit output)
instead of SipHash's 128-bit key. However, this may appeal to some
high-performance `jhash` users.
HalfSipHash support is provided through the "hsiphash" family of functions.
.. warning::
Do not ever use HalfSipHash except for as a hashtable key function, and
only then when you can be absolutely certain that the outputs will never
be transmitted out of the kernel. This is only remotely useful over
`jhash` as a means of mitigating hashtable flooding denial of service
Do not ever use the hsiphash functions except for as a hashtable key
function, and only then when you can be absolutely certain that the outputs
will never be transmitted out of the kernel. This is only remotely useful
over `jhash` as a means of mitigating hashtable flooding denial of service
attacks.
Generating a HalfSipHash key
============================
On 64-bit kernels, the hsiphash functions actually implement SipHash-1-3, a
reduced-round variant of SipHash, instead of HalfSipHash-1-3. This is because in
64-bit code, SipHash-1-3 is no slower than HalfSipHash-1-3, and can be faster.
Note, this does *not* mean that in 64-bit kernels the hsiphash functions are the
same as the siphash ones, or that they are secure; the hsiphash functions still
use a less secure reduced-round algorithm and truncate their outputs to 32
bits.
Generating a hsiphash key
=========================
Keys should always be generated from a cryptographically secure source of
random numbers, either using get_random_bytes or get_random_once::
@ -139,8 +149,8 @@ random numbers, either using get_random_bytes or get_random_once::
If you're not deriving your key from here, you're doing it wrong.
Using the HalfSipHash functions
===============================
Using the hsiphash functions
============================
There are two variants of the function, one that takes a list of integers, and
one that takes a buffer::
@ -183,7 +193,7 @@ You may then iterate like usual over the returned hash bucket.
Performance
===========
HalfSipHash is roughly 3 times slower than JenkinsHash. For many replacements,
this will not be a problem, as the hashtable lookup isn't the bottleneck. And
in general, this is probably a good sacrifice to make for the security and DoS
resistance of HalfSipHash.
hsiphash() is roughly 3 times slower than jhash(). For many replacements, this
will not be a problem, as the hashtable lookup isn't the bottleneck. And in
general, this is probably a good sacrifice to make for the security and DoS
resistance of hsiphash().