]>
Commit | Line | Data |
---|---|---|
2c956a60 JD |
1 | SipHash - a short input PRF |
2 | ----------------------------------------------- | |
3 | Written by Jason A. Donenfeld <jason@zx2c4.com> | |
4 | ||
5 | SipHash is a cryptographically secure PRF -- a keyed hash function -- that | |
6 | performs very well for short inputs, hence the name. It was designed by | |
7 | cryptographers Daniel J. Bernstein and Jean-Philippe Aumasson. It is intended | |
8 | as a replacement for some uses of: `jhash`, `md5_transform`, `sha_transform`, | |
9 | and so forth. | |
10 | ||
11 | SipHash takes a secret key filled with randomly generated numbers and either | |
12 | an input buffer or several input integers. It spits out an integer that is | |
13 | indistinguishable from random. You may then use that integer as part of secure | |
14 | sequence numbers, secure cookies, or mask it off for use in a hash table. | |
15 | ||
16 | 1. Generating a key | |
17 | ||
18 | Keys should always be generated from a cryptographically secure source of | |
19 | random numbers, either using get_random_bytes or get_random_once: | |
20 | ||
21 | siphash_key_t key; | |
22 | get_random_bytes(&key, sizeof(key)); | |
23 | ||
24 | If you're not deriving your key from here, you're doing it wrong. | |
25 | ||
26 | 2. Using the functions | |
27 | ||
28 | There are two variants of the function, one that takes a list of integers, and | |
29 | one that takes a buffer: | |
30 | ||
31 | u64 siphash(const void *data, size_t len, const siphash_key_t *key); | |
32 | ||
33 | And: | |
34 | ||
35 | u64 siphash_1u64(u64, const siphash_key_t *key); | |
36 | u64 siphash_2u64(u64, u64, const siphash_key_t *key); | |
37 | u64 siphash_3u64(u64, u64, u64, const siphash_key_t *key); | |
38 | u64 siphash_4u64(u64, u64, u64, u64, const siphash_key_t *key); | |
39 | u64 siphash_1u32(u32, const siphash_key_t *key); | |
40 | u64 siphash_2u32(u32, u32, const siphash_key_t *key); | |
41 | u64 siphash_3u32(u32, u32, u32, const siphash_key_t *key); | |
42 | u64 siphash_4u32(u32, u32, u32, u32, const siphash_key_t *key); | |
43 | ||
44 | If you pass the generic siphash function something of a constant length, it | |
45 | will constant fold at compile-time and automatically choose one of the | |
46 | optimized functions. | |
47 | ||
48 | 3. Hashtable key function usage: | |
49 | ||
50 | struct some_hashtable { | |
51 | DECLARE_HASHTABLE(hashtable, 8); | |
52 | siphash_key_t key; | |
53 | }; | |
54 | ||
55 | void init_hashtable(struct some_hashtable *table) | |
56 | { | |
57 | get_random_bytes(&table->key, sizeof(table->key)); | |
58 | } | |
59 | ||
60 | static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input) | |
61 | { | |
62 | return &table->hashtable[siphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)]; | |
63 | } | |
64 | ||
65 | You may then iterate like usual over the returned hash bucket. | |
66 | ||
67 | 4. Security | |
68 | ||
69 | SipHash has a very high security margin, with its 128-bit key. So long as the | |
70 | key is kept secret, it is impossible for an attacker to guess the outputs of | |
71 | the function, even if being able to observe many outputs, since 2^128 outputs | |
72 | is significant. | |
73 | ||
74 | Linux implements the "2-4" variant of SipHash. | |
75 | ||
76 | 5. Struct-passing Pitfalls | |
77 | ||
78 | Often times the XuY functions will not be large enough, and instead you'll | |
79 | want to pass a pre-filled struct to siphash. When doing this, it's important | |
80 | to always ensure the struct has no padding holes. The easiest way to do this | |
81 | is to simply arrange the members of the struct in descending order of size, | |
82 | and to use offsetendof() instead of sizeof() for getting the size. For | |
83 | performance reasons, if possible, it's probably a good thing to align the | |
84 | struct to the right boundary. Here's an example: | |
85 | ||
86 | const struct { | |
87 | struct in6_addr saddr; | |
88 | u32 counter; | |
89 | u16 dport; | |
90 | } __aligned(SIPHASH_ALIGNMENT) combined = { | |
91 | .saddr = *(struct in6_addr *)saddr, | |
92 | .counter = counter, | |
93 | .dport = dport | |
94 | }; | |
95 | u64 h = siphash(&combined, offsetofend(typeof(combined), dport), &secret); | |
96 | ||
97 | 6. Resources | |
98 | ||
99 | Read the SipHash paper if you're interested in learning more: | |
100 | https://131002.net/siphash/siphash.pdf | |
1ae2324f JD |
101 | |
102 | ||
103 | ~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~ | |
104 | ||
105 | HalfSipHash - SipHash's insecure younger cousin | |
106 | ----------------------------------------------- | |
107 | Written by Jason A. Donenfeld <jason@zx2c4.com> | |
108 | ||
109 | On the off-chance that SipHash is not fast enough for your needs, you might be | |
110 | able to justify using HalfSipHash, a terrifying but potentially useful | |
111 | possibility. HalfSipHash cuts SipHash's rounds down from "2-4" to "1-3" and, | |
112 | even scarier, uses an easily brute-forcable 64-bit key (with a 32-bit output) | |
113 | instead of SipHash's 128-bit key. However, this may appeal to some | |
114 | high-performance `jhash` users. | |
115 | ||
116 | Danger! | |
117 | ||
118 | Do not ever use HalfSipHash except for as a hashtable key function, and only | |
119 | then when you can be absolutely certain that the outputs will never be | |
120 | transmitted out of the kernel. This is only remotely useful over `jhash` as a | |
121 | means of mitigating hashtable flooding denial of service attacks. | |
122 | ||
123 | 1. Generating a key | |
124 | ||
125 | Keys should always be generated from a cryptographically secure source of | |
126 | random numbers, either using get_random_bytes or get_random_once: | |
127 | ||
128 | hsiphash_key_t key; | |
129 | get_random_bytes(&key, sizeof(key)); | |
130 | ||
131 | If you're not deriving your key from here, you're doing it wrong. | |
132 | ||
133 | 2. Using the functions | |
134 | ||
135 | There are two variants of the function, one that takes a list of integers, and | |
136 | one that takes a buffer: | |
137 | ||
138 | u32 hsiphash(const void *data, size_t len, const hsiphash_key_t *key); | |
139 | ||
140 | And: | |
141 | ||
142 | u32 hsiphash_1u32(u32, const hsiphash_key_t *key); | |
143 | u32 hsiphash_2u32(u32, u32, const hsiphash_key_t *key); | |
144 | u32 hsiphash_3u32(u32, u32, u32, const hsiphash_key_t *key); | |
145 | u32 hsiphash_4u32(u32, u32, u32, u32, const hsiphash_key_t *key); | |
146 | ||
147 | If you pass the generic hsiphash function something of a constant length, it | |
148 | will constant fold at compile-time and automatically choose one of the | |
149 | optimized functions. | |
150 | ||
151 | 3. Hashtable key function usage: | |
152 | ||
153 | struct some_hashtable { | |
154 | DECLARE_HASHTABLE(hashtable, 8); | |
155 | hsiphash_key_t key; | |
156 | }; | |
157 | ||
158 | void init_hashtable(struct some_hashtable *table) | |
159 | { | |
160 | get_random_bytes(&table->key, sizeof(table->key)); | |
161 | } | |
162 | ||
163 | static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input) | |
164 | { | |
165 | return &table->hashtable[hsiphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)]; | |
166 | } | |
167 | ||
168 | You may then iterate like usual over the returned hash bucket. | |
169 | ||
170 | 4. Performance | |
171 | ||
172 | HalfSipHash is roughly 3 times slower than JenkinsHash. For many replacements, | |
173 | this will not be a problem, as the hashtable lookup isn't the bottleneck. And | |
174 | in general, this is probably a good sacrifice to make for the security and DoS | |
175 | resistance of HalfSipHash. |