[PATCH v2] siphash: update the hsiphash documentation

[PATCH v2] siphash: update the hsiphash documentation

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

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>
---

v2: focus the documentation further on the hsiphash functions, so that
    it doesn't need to describe other uses of the HalfSipHash algorithm.

 Documentation/security/siphash.rst | 39 ++++++++++++++++++------------
 1 file changed, 23 insertions(+), 16 deletions(-)

diff --git a/Documentation/security/siphash.rst b/Documentation/security/siphash.rst
index bd9363025fcbc..d66f0b624131d 100644
--- a/Documentation/security/siphash.rst
+++ b/Documentation/security/siphash.rst
@@ -121,26 +121,33 @@ 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!
+HalfSipHash support is provided through the "hsiphash" family of functions.
 
-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.
+**Danger!** 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 an insecure 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:
+random numbers, either using get_random_bytes or get_random_once::
 
-hsiphash_key_t key;
-get_random_bytes(&key, sizeof(key));
+	hsiphash_key_t key;
+	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::
@@ -183,7 +190,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().
-- 
2.35.2

Re: [PATCH v2] siphash: update the hsiphash documentation

[Jason A. Donenfeld]

Hi Eric,

On Thu, Apr 21, 2022 at 05:27:31PM -0700, Eric Biggers wrote:
> +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 an insecure reduced-round algorithm and truncate their outputs to 32 bits.
 
Small nit: "less secure" rather than "insecure", as I don't think
there's a super realistic attack against 1-3. I can make that change
when committing if that's fine by you.

Jason

Re: [PATCH v2] siphash: update the hsiphash documentation

[Eric Biggers]

On Fri, Apr 22, 2022 at 02:40:36AM +0200, Jason A. Donenfeld wrote:
> Hi Eric,
> 
> On Thu, Apr 21, 2022 at 05:27:31PM -0700, Eric Biggers wrote:
> > +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 an insecure reduced-round algorithm and truncate their outputs to 32 bits.
>  
> Small nit: "less secure" rather than "insecure", as I don't think
> there's a super realistic attack against 1-3. I can make that change
> when committing if that's fine by you.
> 
> Jason

That's fine, assuming that you're just talking about SipHash-1-3, not also
HalfSipHash-1-3.  The section title is "HalfSipHash - SipHash's insecure younger
cousin", so the word "insecure" is applied to HalfSipHash already.

- Eric