linux-kernel - [PATCH] siphash: update the HalfSipHash documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-Id: <20220421204320.258010-1-ebiggers@kernel.org>
Date:   Thu, 21 Apr 2022 13:43:20 -0700
From:   Eric Biggers <ebiggers@...nel.org>
To:     "Jason A . Donenfeld " <Jason@...c4.com>
Cc:     linux-kernel@...r.kernel.org, linux-crypto@...r.kernel.org,
        Theodore Ts'o <tytso@....edu>
Subject: [PATCH] siphash: update the HalfSipHash documentation

From: Eric Biggers <ebiggers@...gle.com>

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@...gle.com>
---
 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