From: Eric Biggers <ebiggers@xxxxxxxxxx> Update the documentation for HalfSipHash to correctly explain that the kernel actually implements either HalfSipHash-1-3 or SipHash-1-3, and that HalfSipHash-1-3 is not entirely limited to hashtable functions, with it now being used in the interrupt entropy accumulator. Signed-off-by: Eric Biggers <ebiggers@xxxxxxxxxx> --- Documentation/security/siphash.rst | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/Documentation/security/siphash.rst b/Documentation/security/siphash.rst index bd9363025fcbc..9b079b2ac2a1a 100644 --- a/Documentation/security/siphash.rst +++ b/Documentation/security/siphash.rst @@ -121,15 +121,23 @@ 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. -Danger! +**Danger!** HalfSipHash should only be used in a very limited set of use cases +where nothing better is possible, namely: -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 attacks. +- Hashtable key functions, where 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 -============================ +- The interrupt entropy accumulator in ``drivers/char/random.c``. This is a very + special case; do *not* use this as example code for anything else. + +Note, 64-bit kernels actually implement SipHash-1-3 instead of HalfSipHash-1-3; +the "hsiphash" functions redirect to either algorithm. This is done for +performance reasons; it does *not* mean that the hsiphash functions are +cryptographically secure on 64-bit platforms. + +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 +147,8 @@ get_random_bytes(&key, sizeof(key)); 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:: -- 2.35.2
