From: Eric Biggers <ebiggers@kernel.org>
To: "Jason A . Donenfeld " <Jason@zx2c4.com>
Cc: linux-kernel@vger.kernel.org, linux-crypto@vger.kernel.org,
Theodore Ts'o <tytso@mit.edu>
Subject: [PATCH] siphash: update the HalfSipHash documentation
Date: Thu, 21 Apr 2022 13:43:20 -0700 [thread overview]
Message-ID: <20220421204320.258010-1-ebiggers@kernel.org> (raw)
From: Eric Biggers <ebiggers@google.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@google.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
next reply other threads:[~2022-04-21 20:44 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-04-21 20:43 Eric Biggers [this message]
2022-04-21 23:08 ` [PATCH] siphash: update the HalfSipHash documentation Jason A. Donenfeld
2022-04-21 23:40 ` Eric Biggers
2022-04-21 23:42 ` Jason A. Donenfeld
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220421204320.258010-1-ebiggers@kernel.org \
--to=ebiggers@kernel.org \
--cc=Jason@zx2c4.com \
--cc=linux-crypto@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=tytso@mit.edu \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).