200 lines
6.9 KiB
ReStructuredText
200 lines
6.9 KiB
ReStructuredText
|
===========================
|
||
|
SipHash - a short input PRF
|
||
|
===========================
|
||
|
|
||
|
:Author: Written by Jason A. Donenfeld <jason@zx2c4.com>
|
||
|
|
||
|
SipHash is a cryptographically secure PRF -- a keyed hash function -- that
|
||
|
performs very well for short inputs, hence the name. It was designed by
|
||
|
cryptographers Daniel J. Bernstein and Jean-Philippe Aumasson. It is intended
|
||
|
as a replacement for some uses of: `jhash`, `md5_transform`, `sha1_transform`,
|
||
|
and so forth.
|
||
|
|
||
|
SipHash takes a secret key filled with randomly generated numbers and either
|
||
|
an input buffer or several input integers. It spits out an integer that is
|
||
|
indistinguishable from random. You may then use that integer as part of secure
|
||
|
sequence numbers, secure cookies, or mask it off for use in a hash table.
|
||
|
|
||
|
Generating a key
|
||
|
================
|
||
|
|
||
|
Keys should always be generated from a cryptographically secure source of
|
||
|
random numbers, either using get_random_bytes or get_random_once::
|
||
|
|
||
|
siphash_key_t key;
|
||
|
get_random_bytes(&key, sizeof(key));
|
||
|
|
||
|
If you're not deriving your key from here, you're doing it wrong.
|
||
|
|
||
|
Using the functions
|
||
|
===================
|
||
|
|
||
|
There are two variants of the function, one that takes a list of integers, and
|
||
|
one that takes a buffer::
|
||
|
|
||
|
u64 siphash(const void *data, size_t len, const siphash_key_t *key);
|
||
|
|
||
|
And::
|
||
|
|
||
|
u64 siphash_1u64(u64, const siphash_key_t *key);
|
||
|
u64 siphash_2u64(u64, u64, const siphash_key_t *key);
|
||
|
u64 siphash_3u64(u64, u64, u64, const siphash_key_t *key);
|
||
|
u64 siphash_4u64(u64, u64, u64, u64, const siphash_key_t *key);
|
||
|
u64 siphash_1u32(u32, const siphash_key_t *key);
|
||
|
u64 siphash_2u32(u32, u32, const siphash_key_t *key);
|
||
|
u64 siphash_3u32(u32, u32, u32, const siphash_key_t *key);
|
||
|
u64 siphash_4u32(u32, u32, u32, u32, const siphash_key_t *key);
|
||
|
|
||
|
If you pass the generic siphash function something of a constant length, it
|
||
|
will constant fold at compile-time and automatically choose one of the
|
||
|
optimized functions.
|
||
|
|
||
|
Hashtable key function usage::
|
||
|
|
||
|
struct some_hashtable {
|
||
|
DECLARE_HASHTABLE(hashtable, 8);
|
||
|
siphash_key_t key;
|
||
|
};
|
||
|
|
||
|
void init_hashtable(struct some_hashtable *table)
|
||
|
{
|
||
|
get_random_bytes(&table->key, sizeof(table->key));
|
||
|
}
|
||
|
|
||
|
static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
|
||
|
{
|
||
|
return &table->hashtable[siphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
|
||
|
}
|
||
|
|
||
|
You may then iterate like usual over the returned hash bucket.
|
||
|
|
||
|
Security
|
||
|
========
|
||
|
|
||
|
SipHash has a very high security margin, with its 128-bit key. So long as the
|
||
|
key is kept secret, it is impossible for an attacker to guess the outputs of
|
||
|
the function, even if being able to observe many outputs, since 2^128 outputs
|
||
|
is significant.
|
||
|
|
||
|
Linux implements the "2-4" variant of SipHash.
|
||
|
|
||
|
Struct-passing Pitfalls
|
||
|
=======================
|
||
|
|
||
|
Often times the XuY functions will not be large enough, and instead you'll
|
||
|
want to pass a pre-filled struct to siphash. When doing this, it's important
|
||
|
to always ensure the struct has no padding holes. The easiest way to do this
|
||
|
is to simply arrange the members of the struct in descending order of size,
|
||
|
and to use offsetofend() instead of sizeof() for getting the size. For
|
||
|
performance reasons, if possible, it's probably a good thing to align the
|
||
|
struct to the right boundary. Here's an example::
|
||
|
|
||
|
const struct {
|
||
|
struct in6_addr saddr;
|
||
|
u32 counter;
|
||
|
u16 dport;
|
||
|
} __aligned(SIPHASH_ALIGNMENT) combined = {
|
||
|
.saddr = *(struct in6_addr *)saddr,
|
||
|
.counter = counter,
|
||
|
.dport = dport
|
||
|
};
|
||
|
u64 h = siphash(&combined, offsetofend(typeof(combined), dport), &secret);
|
||
|
|
||
|
Resources
|
||
|
=========
|
||
|
|
||
|
Read the SipHash paper if you're interested in learning more:
|
||
|
https://131002.net/siphash/siphash.pdf
|
||
|
|
||
|
-------------------------------------------------------------------------------
|
||
|
|
||
|
===============================================
|
||
|
HalfSipHash - SipHash's insecure younger cousin
|
||
|
===============================================
|
||
|
|
||
|
:Author: Written by Jason A. Donenfeld <jason@zx2c4.com>
|
||
|
|
||
|
On the off-chance that SipHash is not fast enough for your needs, you might be
|
||
|
able to justify using HalfSipHash, a terrifying but potentially useful
|
||
|
possibility. HalfSipHash cuts SipHash's rounds down from "2-4" to "1-3" and,
|
||
|
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 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.
|
||
|
|
||
|
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::
|
||
|
|
||
|
hsiphash_key_t key;
|
||
|
get_random_bytes(&key, sizeof(key));
|
||
|
|
||
|
If you're not deriving your key from here, you're doing it wrong.
|
||
|
|
||
|
Using the hsiphash functions
|
||
|
============================
|
||
|
|
||
|
There are two variants of the function, one that takes a list of integers, and
|
||
|
one that takes a buffer::
|
||
|
|
||
|
u32 hsiphash(const void *data, size_t len, const hsiphash_key_t *key);
|
||
|
|
||
|
And::
|
||
|
|
||
|
u32 hsiphash_1u32(u32, const hsiphash_key_t *key);
|
||
|
u32 hsiphash_2u32(u32, u32, const hsiphash_key_t *key);
|
||
|
u32 hsiphash_3u32(u32, u32, u32, const hsiphash_key_t *key);
|
||
|
u32 hsiphash_4u32(u32, u32, u32, u32, const hsiphash_key_t *key);
|
||
|
|
||
|
If you pass the generic hsiphash function something of a constant length, it
|
||
|
will constant fold at compile-time and automatically choose one of the
|
||
|
optimized functions.
|
||
|
|
||
|
Hashtable key function usage
|
||
|
============================
|
||
|
|
||
|
::
|
||
|
|
||
|
struct some_hashtable {
|
||
|
DECLARE_HASHTABLE(hashtable, 8);
|
||
|
hsiphash_key_t key;
|
||
|
};
|
||
|
|
||
|
void init_hashtable(struct some_hashtable *table)
|
||
|
{
|
||
|
get_random_bytes(&table->key, sizeof(table->key));
|
||
|
}
|
||
|
|
||
|
static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
|
||
|
{
|
||
|
return &table->hashtable[hsiphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
|
||
|
}
|
||
|
|
||
|
You may then iterate like usual over the returned hash bucket.
|
||
|
|
||
|
Performance
|
||
|
===========
|
||
|
|
||
|
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().
|