From patchwork Thu Apr 21 20:43:20 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 565040 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 80CADC433F5 for ; Thu, 21 Apr 2022 20:44:17 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1392535AbiDUUrF (ORCPT ); Thu, 21 Apr 2022 16:47:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:55486 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1349411AbiDUUrF (ORCPT ); Thu, 21 Apr 2022 16:47:05 -0400 Received: from ams.source.kernel.org (ams.source.kernel.org [IPv6:2604:1380:4601:e00::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 41A234E391; Thu, 21 Apr 2022 13:44:14 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id 082E1B828D8; Thu, 21 Apr 2022 20:44:13 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id A652DC385A7; Thu, 21 Apr 2022 20:44:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1650573851; bh=8xH5wV1KvrkMTwGdQxQZPmkY2ffhRKacNykV31qXzQA=; h=From:To:Cc:Subject:Date:From; b=ll979oUoHbSxXuVHKN9EkSPu3NI0XxkU+Xe2izKWxGiK6wBGtmrtZA8ncRq8kIuJ0 u7gXJh+q/F88e4uAwPEiJKrDm1jy4tT8iH20ArGHJNFC4DYpRwYHEkUzYSXNWPKKgQ RRtZ74nI1LStL9ozF3v/tG77EEp2XEjGYgfV1SPU3dRmzzUbDGCGwTPl66RD7z8SJi k6+i1Er7adPa015OAr2wRzO/WTikDK6zO6zm6FLxbr/3qH5tUTF8UP9bjr2DfTZh/T n/WippRsMYbWH/HkzfV3XIgCbZWiTIGDfxIOpVOhmFX80VgFjNIMxteE26O9KK53/k wCI8RYjAP2YPg== From: Eric Biggers To: "Jason A . Donenfeld " Cc: linux-kernel@vger.kernel.org, linux-crypto@vger.kernel.org, Theodore Ts'o Subject: [PATCH] siphash: update the HalfSipHash documentation Date: Thu, 21 Apr 2022 13:43:20 -0700 Message-Id: <20220421204320.258010-1-ebiggers@kernel.org> X-Mailer: git-send-email 2.35.2 MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-crypto@vger.kernel.org From: Eric Biggers 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 --- 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::