From ec862155c3ccbde59644336eec58468e7d07519b Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Sun, 17 Apr 2022 14:50:57 +0700 Subject: Documentation: siphash: convert danger note to warning for HalfSipHash Render danger paragraph into warning block for emphasization. Cc: Jonathan Corbet Cc: Eric Biggers Cc: Herbert Xu Cc: Mauro Carvalho Chehab Cc: linux-kernel@vger.kernel.org Signed-off-by: Bagas Sanjaya Signed-off-by: Jonathan Corbet Signed-off-by: Jason A. Donenfeld --- Documentation/security/siphash.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/security/siphash.rst b/Documentation/security/siphash.rst index bd9363025fcb..42794a7e052f 100644 --- a/Documentation/security/siphash.rst +++ b/Documentation/security/siphash.rst @@ -121,12 +121,12 @@ 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! - -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. +.. 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 + attacks. Generating a HalfSipHash key ============================ -- cgit v1.2.3 From 2fbfeb4fa61684955980b99603c29d2002a67118 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Sun, 17 Apr 2022 14:50:58 +0700 Subject: Documentation: siphash: enclose HalfSipHash usage example in the literal block Render usage example of HalfSipHash function as code block by using literal block syntax. Cc: Jonathan Corbet Cc: Eric Biggers Cc: Herbert Xu Cc: Mauro Carvalho Chehab Cc: linux-kernel@vger.kernel.org Signed-off-by: Bagas Sanjaya Signed-off-by: Jonathan Corbet Signed-off-by: Jason A. Donenfeld --- Documentation/security/siphash.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/security/siphash.rst b/Documentation/security/siphash.rst index 42794a7e052f..96b1492f4773 100644 --- a/Documentation/security/siphash.rst +++ b/Documentation/security/siphash.rst @@ -132,10 +132,10 @@ Generating a HalfSipHash 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. -- cgit v1.2.3 From 5a7e470e460fb90657343d843732325e53bb875f Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Thu, 21 Apr 2022 17:27:31 -0700 Subject: Documentation: siphash: disambiguate HalfSipHash algorithm from hsiphash functions 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 Signed-off-by: Jason A. Donenfeld --- Documentation/security/siphash.rst | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) (limited to 'Documentation') diff --git a/Documentation/security/siphash.rst b/Documentation/security/siphash.rst index 96b1492f4773..a10380cb78e5 100644 --- a/Documentation/security/siphash.rst +++ b/Documentation/security/siphash.rst @@ -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(). -- cgit v1.2.3