siphash: update the HalfSipHash documentation
Subsystems (2)
PATCH 1/1 siphash: update the HalfSipHash documentation
From: Eric Biggers <[email protected]>
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.
--- Documentation/security/siphash.rst | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-)
Documentation/security/siphash.rst +17 -9
@@ -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::
Signature · 1 line
2.35.2
Hi Eric,
Documentation/security/siphash.rst even scarier, uses an easily brute-forcable 64-bit key (with a 32-bit output) · line 129
Quoted 11 lines · Eric Biggers
Documentation/security/siphash.rst +5
-5-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.
I think we should actually drop this chunk of the patch. You wrote in your commit message, "HalfSipHash-1-3 is not entirely limited to hashtable functions, with it now being used in the interrupt entropy accumulator." But in fact, random.c uses HalfSipHash-1, with no three round finalization (since we use BLAKE2s for that). So it's not _quite_ the same thing. If it were, we could have gotten away by just calling the actual hsiphash function, but instead it's just applying the round function as a permutation.
If you feel strongly that somebody might accidentally copy and paste that after grepping for halfsiphash and trying to figure out how to use it, I suppose we could keep this. But it strikes me as very much not the same thing as the hsiphash_* family of functions.
Jason
Quoted 24 lines · Jason A. Donenfeld
Hi Eric,
Documentation/security/siphash.rst even scarier, uses an easily brute-forcable 64-bit key (with a 32-bit output) · line 129
Quoted 11 lines · Eric Biggers
Documentation/security/siphash.rst +5
-5-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.I think we should actually drop this chunk of the patch. You wrote in your commit message, "HalfSipHash-1-3 is not entirely limited to hashtable functions, with it now being used in the interrupt entropy accumulator." But in fact,
random.cuses HalfSipHash-1, with no three round finalization (since we use BLAKE2s for that). So it's not _quite_ the same thing. If it were, we could have gotten away by just calling the actual hsiphash function, but instead it's just applying the round function as a permutation.
Quoted 4 lines
If you feel strongly that somebody might accidentally copy and paste that after grepping for halfsiphash and trying to figure out how to use it, I suppose we could keep this. But it strikes me as very much not the same thing as the hsiphash_* family of functions.
Well, this documentation starts out by introducing HalfSipHash, and then moves on to the the hsiphash functions. This part is still talking about HalfSipHash, so in that context the mention of its use in random.c is relevant. But I could certainly reword it to make it all about the hsiphash functions, with HalfSipHash being mentioned more as an implementation detail.
- Eric
Hi Eric,
Quoted 5 lines · Eric Biggers
Well, this documentation starts out by introducing HalfSipHash, and then moves on to the the hsiphash functions. This part is still talking about HalfSipHash, so in that context the mention of its use in
random.cis relevant. But I could certainly reword it to make it all about the hsiphash functions, with HalfSipHash being mentioned more as an implementation detail.
Alright, so let's just drop that hunk for v2 then.
Jason