Jason A. Donenfeld | c626dde | 2017-01-08 13:54:00 +0100 | [diff] [blame] | 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 |
Jason A. Donenfeld | 72cabd4 | 2017-01-08 13:54:01 +0100 | [diff] [blame] | 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. |