Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Merge tag 'random-5.18-rc5-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/crng/random
Pull random number generator fixes from Jason Donenfeld:
- Eric noticed that the memmove() in crng_fast_key_erasure() was bogus,
so this has been changed to a memcpy() and the confusing situation
clarified with a detailed comment.
- [Half]SipHash documentation updates from Bagas and Eric, after Eric
pointed out that the use of HalfSipHash in random.c made a bit of the
text potentially misleading.
* tag 'random-5.18-rc5-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/crng/random:
Documentation: siphash: disambiguate HalfSipHash algorithm from hsiphash functions
Documentation: siphash: enclose HalfSipHash usage example in the literal block
Documentation: siphash: convert danger note to warning for HalfSipHash
random: document crng_fast_key_erasure() destination possibility
+34
-17
+26
-16
Documentation/security/siphash.rst
+26
-16
Documentation/security/siphash.rst
···
121
121
instead of SipHash's 128-bit key. However, this may appeal to some
122
122
high-performance `jhash` users.
123
123
124
-
Danger!
124
+
HalfSipHash support is provided through the "hsiphash" family of functions.
125
125
126
-
Do not ever use HalfSipHash except for as a hashtable key function, and only
127
-
then when you can be absolutely certain that the outputs will never be
128
-
transmitted out of the kernel. This is only remotely useful over `jhash` as a
129
-
means of mitigating hashtable flooding denial of service attacks.
126
+
.. warning::
127
+
Do not ever use the hsiphash functions except for as a hashtable key
128
+
function, and only then when you can be absolutely certain that the outputs
129
+
will never be transmitted out of the kernel. This is only remotely useful
130
+
over `jhash` as a means of mitigating hashtable flooding denial of service
131
+
attacks.
130
132
131
-
Generating a HalfSipHash key
132
-
============================
133
+
On 64-bit kernels, the hsiphash functions actually implement SipHash-1-3, a
134
+
reduced-round variant of SipHash, instead of HalfSipHash-1-3. This is because in
135
+
64-bit code, SipHash-1-3 is no slower than HalfSipHash-1-3, and can be faster.
136
+
Note, this does *not* mean that in 64-bit kernels the hsiphash functions are the
137
+
same as the siphash ones, or that they are secure; the hsiphash functions still
138
+
use a less secure reduced-round algorithm and truncate their outputs to 32
139
+
bits.
140
+
141
+
Generating a hsiphash key
142
+
=========================
133
143
134
144
Keys should always be generated from a cryptographically secure source of
135
-
random numbers, either using get_random_bytes or get_random_once:
145
+
random numbers, either using get_random_bytes or get_random_once::
136
146
137
-
hsiphash_key_t key;
138
-
get_random_bytes(&key, sizeof(key));
147
+
hsiphash_key_t key;
148
+
get_random_bytes(&key, sizeof(key));
139
149
140
150
If you're not deriving your key from here, you're doing it wrong.
141
151
142
-
Using the HalfSipHash functions
143
-
===============================
152
+
Using the hsiphash functions
153
+
============================
144
154
145
155
There are two variants of the function, one that takes a list of integers, and
146
156
one that takes a buffer::
···
193
183
Performance
194
184
===========
195
185
196
-
HalfSipHash is roughly 3 times slower than JenkinsHash. For many replacements,
197
-
this will not be a problem, as the hashtable lookup isn't the bottleneck. And
198
-
in general, this is probably a good sacrifice to make for the security and DoS
199
-
resistance of HalfSipHash.
186
+
hsiphash() is roughly 3 times slower than jhash(). For many replacements, this
187
+
will not be a problem, as the hashtable lookup isn't the bottleneck. And in
188
+
general, this is probably a good sacrifice to make for the security and DoS
189
+
resistance of hsiphash().
+8
-1
drivers/char/random.c
+8
-1
drivers/char/random.c
···
318
318
* the resultant ChaCha state to the user, along with the second
319
319
* half of the block containing 32 bytes of random data that may
320
320
* be used; random_data_len may not be greater than 32.
321
+
*
322
+
* The returned ChaCha state contains within it a copy of the old
323
+
* key value, at index 4, so the state should always be zeroed out
324
+
* immediately after using in order to maintain forward secrecy.
325
+
* If the state cannot be erased in a timely manner, then it is
326
+
* safer to set the random_data parameter to &chacha_state[4] so
327
+
* that this function overwrites it before returning.
321
328
*/
322
329
static void crng_fast_key_erasure(u8 key[CHACHA_KEY_SIZE],
323
330
u32 chacha_state[CHACHA_STATE_WORDS],
···
340
333
chacha20_block(chacha_state, first_block);
341
334
342
335
memcpy(key, first_block, CHACHA_KEY_SIZE);
343
-
memmove(random_data, first_block + CHACHA_KEY_SIZE, random_data_len);
336
+
memcpy(random_data, first_block + CHACHA_KEY_SIZE, random_data_len);
344
337
memzero_explicit(first_block, sizeof(first_block));
345
338
}
346
339