1//! An implementation of SipHash.
2
3#![allow(deprecated)] // the types in this module are deprecated
4
5use crate::marker::PhantomData;
6use crate::{cmp, ptr};
7
8/// An implementation of SipHash 1-3.
9///
10/// This is currently the default hashing function used by standard library
11/// (e.g., `collections::HashMap` uses it by default).
12///
13/// See: <https://github.com/veorq/SipHash>
14#[unstable(
15 feature = "hashmap_internals",
16 issue = "none",
17 reason = "use `std::hash::DefaultHasher` instead"
18)]
19#[derive(Debug, Clone, Default)]
20#[doc(hidden)]
21pub struct SipHasher13 {
22 hasher: Hasher<Sip13Rounds>,
23}
24
25/// An implementation of SipHash 2-4.
26///
27/// See: <https://github.com/veorq/SipHash>
28#[unstable(feature = "hashmap_internals", issue = "none")]
29#[derive(Debug, Clone, Default)]
30struct SipHasher24 {
31 hasher: Hasher<Sip24Rounds>,
32}
33
34/// An implementation of SipHash 2-4.
35///
36/// See: <https://github.com/veorq/SipHash>
37///
38/// SipHash is a general-purpose hashing function: it runs at a good
39/// speed (competitive with Spooky and City) and permits strong _keyed_
40/// hashing. This lets you key your hash tables from a strong RNG, such as
41/// [`rand::os::OsRng`](https://docs.rs/rand/latest/rand/rngs/struct.OsRng.html).
42///
43/// Although the SipHash algorithm is considered to be generally strong,
44/// it is not intended for cryptographic purposes. As such, all
45/// cryptographic uses of this implementation are _strongly discouraged_.
46#[stable(feature = "rust1", since = "1.0.0")]
47#[deprecated(since = "1.13.0", note = "use `std::hash::DefaultHasher` instead")]
48#[derive(Debug, Clone, Default)]
49pub struct SipHasher(SipHasher24);
50
51#[derive(Debug)]
52struct Hasher<S: Sip> {
53 k0: u64,
54 k1: u64,
55 length: usize, // how many bytes we've processed
56 state: State, // hash State
57 tail: u64, // unprocessed bytes le
58 ntail: usize, // how many bytes in tail are valid
59 _marker: PhantomData<S>,
60}
61
62#[derive(Debug, Clone, Copy)]
63#[repr(C)]
64struct State {
65 // v0, v2 and v1, v3 show up in pairs in the algorithm,
66 // and simd implementations of SipHash will use vectors
67 // of v02 and v13. By placing them in this order in the struct,
68 // the compiler can pick up on just a few simd optimizations by itself.
69 v0: u64,
70 v2: u64,
71 v1: u64,
72 v3: u64,
73}
74
75macro_rules! compress {
76 ($state:expr) => {{ compress!($state.v0, $state.v1, $state.v2, $state.v3) }};
77 ($v0:expr, $v1:expr, $v2:expr, $v3:expr) => {{
78 $v0 = $v0.wrapping_add($v1);
79 $v2 = $v2.wrapping_add($v3);
80 $v1 = $v1.rotate_left(13);
81 $v1 ^= $v0;
82 $v3 = $v3.rotate_left(16);
83 $v3 ^= $v2;
84 $v0 = $v0.rotate_left(32);
85
86 $v2 = $v2.wrapping_add($v1);
87 $v0 = $v0.wrapping_add($v3);
88 $v1 = $v1.rotate_left(17);
89 $v1 ^= $v2;
90 $v3 = $v3.rotate_left(21);
91 $v3 ^= $v0;
92 $v2 = $v2.rotate_left(32);
93 }};
94}
95
96/// Loads an integer of the desired type from a byte stream, in LE order. Uses
97/// `copy_nonoverlapping` to let the compiler generate the most efficient way
98/// to load it from a possibly unaligned address.
99///
100/// Safety: this performs unchecked indexing of `$buf` at
101/// `$i..$i+size_of::<$int_ty>()`, so that must be in-bounds.
102macro_rules! load_int_le {
103 ($buf:expr, $i:expr, $int_ty:ident) => {{
104 debug_assert!($i + size_of::<$int_ty>() <= $buf.len());
105 let mut data = 0 as $int_ty;
106 ptr::copy_nonoverlapping(
107 $buf.as_ptr().add($i),
108 &mut data as *mut _ as *mut u8,
109 size_of::<$int_ty>(),
110 );
111 data.to_le()
112 }};
113}
114
115/// Loads a u64 using up to 7 bytes of a byte slice. It looks clumsy but the
116/// `copy_nonoverlapping` calls that occur (via `load_int_le!`) all have fixed
117/// sizes and avoid calling `memcpy`, which is good for speed.
118///
119/// Safety: this performs unchecked indexing of `buf` at `start..start+len`, so
120/// that must be in-bounds.
121#[inline]
122unsafe fn u8to64_le(buf: &[u8], start: usize, len: usize) -> u64 {
123 debug_assert!(len < 8);
124 let mut i: usize = 0; // current byte index (from LSB) in the output u64
125 let mut out: u64 = 0;
126 if i + 3 < len {
127 // SAFETY: `i` cannot be greater than `len`, and the caller must guarantee
128 // that the index start..start+len is in bounds.
129 out = unsafe { load_int_le!(buf, start + i, u32) } as u64;
130 i += 4;
131 }
132 if i + 1 < len {
133 // SAFETY: same as above.
134 out |= (unsafe { load_int_le!(buf, start + i, u16) } as u64) << (i * 8);
135 i += 2
136 }
137 if i < len {
138 // SAFETY: same as above.
139 out |= (unsafe { *buf.get_unchecked(index:start + i) } as u64) << (i * 8);
140 i += 1;
141 }
142 debug_assert_eq!(i, len);
143 out
144}
145
146impl SipHasher {
147 /// Creates a new `SipHasher` with the two initial keys set to 0.
148 #[inline]
149 #[stable(feature = "rust1", since = "1.0.0")]
150 #[deprecated(since = "1.13.0", note = "use `std::hash::DefaultHasher` instead")]
151 #[must_use]
152 pub fn new() -> SipHasher {
153 SipHasher::new_with_keys(key0:0, key1:0)
154 }
155
156 /// Creates a `SipHasher` that is keyed off the provided keys.
157 #[inline]
158 #[stable(feature = "rust1", since = "1.0.0")]
159 #[deprecated(since = "1.13.0", note = "use `std::hash::DefaultHasher` instead")]
160 #[must_use]
161 pub fn new_with_keys(key0: u64, key1: u64) -> SipHasher {
162 SipHasher(SipHasher24 { hasher: Hasher::new_with_keys(key0, key1) })
163 }
164}
165
166impl SipHasher13 {
167 /// Creates a new `SipHasher13` with the two initial keys set to 0.
168 #[inline]
169 #[unstable(feature = "hashmap_internals", issue = "none")]
170 #[rustc_const_unstable(feature = "const_default", issue = "143894")]
171 pub const fn new() -> SipHasher13 {
172 SipHasher13::new_with_keys(key0:0, key1:0)
173 }
174
175 /// Creates a `SipHasher13` that is keyed off the provided keys.
176 #[inline]
177 #[unstable(feature = "hashmap_internals", issue = "none")]
178 #[rustc_const_unstable(feature = "const_default", issue = "143894")]
179 pub const fn new_with_keys(key0: u64, key1: u64) -> SipHasher13 {
180 SipHasher13 { hasher: Hasher::new_with_keys(key0, key1) }
181 }
182}
183
184impl<S: Sip> Hasher<S> {
185 #[inline]
186 const fn new_with_keys(key0: u64, key1: u64) -> Hasher<S> {
187 let mut state = Hasher {
188 k0: key0,
189 k1: key1,
190 length: 0,
191 state: State { v0: 0, v1: 0, v2: 0, v3: 0 },
192 tail: 0,
193 ntail: 0,
194 _marker: PhantomData,
195 };
196 state.reset();
197 state
198 }
199
200 #[inline]
201 const fn reset(&mut self) {
202 self.length = 0;
203 self.state.v0 = self.k0 ^ 0x736f6d6570736575;
204 self.state.v1 = self.k1 ^ 0x646f72616e646f6d;
205 self.state.v2 = self.k0 ^ 0x6c7967656e657261;
206 self.state.v3 = self.k1 ^ 0x7465646279746573;
207 self.ntail = 0;
208 }
209}
210
211#[stable(feature = "rust1", since = "1.0.0")]
212impl super::Hasher for SipHasher {
213 #[inline]
214 fn write(&mut self, msg: &[u8]) {
215 self.0.hasher.write(bytes:msg)
216 }
217
218 #[inline]
219 fn write_str(&mut self, s: &str) {
220 self.0.hasher.write_str(s);
221 }
222
223 #[inline]
224 fn finish(&self) -> u64 {
225 self.0.hasher.finish()
226 }
227}
228
229#[unstable(feature = "hashmap_internals", issue = "none")]
230impl super::Hasher for SipHasher13 {
231 #[inline]
232 fn write(&mut self, msg: &[u8]) {
233 self.hasher.write(bytes:msg)
234 }
235
236 #[inline]
237 fn write_str(&mut self, s: &str) {
238 self.hasher.write_str(s);
239 }
240
241 #[inline]
242 fn finish(&self) -> u64 {
243 self.hasher.finish()
244 }
245}
246
247impl<S: Sip> super::Hasher for Hasher<S> {
248 // Note: no integer hashing methods (`write_u*`, `write_i*`) are defined
249 // for this type. We could add them, copy the `short_write` implementation
250 // in librustc_data_structures/sip128.rs, and add `write_u*`/`write_i*`
251 // methods to `SipHasher`, `SipHasher13`, and `DefaultHasher`. This would
252 // greatly speed up integer hashing by those hashers, at the cost of
253 // slightly slowing down compile speeds on some benchmarks. See #69152 for
254 // details.
255 #[inline]
256 fn write(&mut self, msg: &[u8]) {
257 let length = msg.len();
258 self.length += length;
259
260 let mut needed = 0;
261
262 if self.ntail != 0 {
263 needed = 8 - self.ntail;
264 // SAFETY: `cmp::min(length, needed)` is guaranteed to not be over `length`
265 self.tail |= unsafe { u8to64_le(msg, 0, cmp::min(length, needed)) } << (8 * self.ntail);
266 if length < needed {
267 self.ntail += length;
268 return;
269 } else {
270 self.state.v3 ^= self.tail;
271 S::c_rounds(&mut self.state);
272 self.state.v0 ^= self.tail;
273 self.ntail = 0;
274 }
275 }
276
277 // Buffered tail is now flushed, process new input.
278 let len = length - needed;
279 let left = len & 0x7; // len % 8
280
281 let mut i = needed;
282 while i < len - left {
283 // SAFETY: because `len - left` is the biggest multiple of 8 under
284 // `len`, and because `i` starts at `needed` where `len` is `length - needed`,
285 // `i + 8` is guaranteed to be less than or equal to `length`.
286 let mi = unsafe { load_int_le!(msg, i, u64) };
287
288 self.state.v3 ^= mi;
289 S::c_rounds(&mut self.state);
290 self.state.v0 ^= mi;
291
292 i += 8;
293 }
294
295 // SAFETY: `i` is now `needed + len.div_euclid(8) * 8`,
296 // so `i + left` = `needed + len` = `length`, which is by
297 // definition equal to `msg.len()`.
298 self.tail = unsafe { u8to64_le(msg, i, left) };
299 self.ntail = left;
300 }
301
302 #[inline]
303 fn write_str(&mut self, s: &str) {
304 // This hasher works byte-wise, and `0xFF` cannot show up in a `str`,
305 // so just hashing the one extra byte is enough to be prefix-free.
306 self.write(s.as_bytes());
307 self.write_u8(0xFF);
308 }
309
310 #[inline]
311 fn finish(&self) -> u64 {
312 let mut state = self.state;
313
314 let b: u64 = ((self.length as u64 & 0xff) << 56) | self.tail;
315
316 state.v3 ^= b;
317 S::c_rounds(&mut state);
318 state.v0 ^= b;
319
320 state.v2 ^= 0xff;
321 S::d_rounds(&mut state);
322
323 state.v0 ^ state.v1 ^ state.v2 ^ state.v3
324 }
325}
326
327impl<S: Sip> Clone for Hasher<S> {
328 #[inline]
329 fn clone(&self) -> Hasher<S> {
330 Hasher {
331 k0: self.k0,
332 k1: self.k1,
333 length: self.length,
334 state: self.state,
335 tail: self.tail,
336 ntail: self.ntail,
337 _marker: self._marker,
338 }
339 }
340}
341
342#[rustc_const_unstable(feature = "const_default", issue = "143894")]
343impl<S: Sip> const Default for Hasher<S> {
344 /// Creates a `Hasher<S>` with the two initial keys set to 0.
345 #[inline]
346 fn default() -> Hasher<S> {
347 Hasher::new_with_keys(key0:0, key1:0)
348 }
349}
350
351#[doc(hidden)]
352trait Sip {
353 fn c_rounds(_: &mut State);
354 fn d_rounds(_: &mut State);
355}
356
357#[derive(Debug, Clone, Default)]
358struct Sip13Rounds;
359
360impl Sip for Sip13Rounds {
361 #[inline]
362 fn c_rounds(state: &mut State) {
363 compress!(state);
364 }
365
366 #[inline]
367 fn d_rounds(state: &mut State) {
368 compress!(state);
369 compress!(state);
370 compress!(state);
371 }
372}
373
374#[derive(Debug, Clone, Default)]
375struct Sip24Rounds;
376
377impl Sip for Sip24Rounds {
378 #[inline]
379 fn c_rounds(state: &mut State) {
380 compress!(state);
381 compress!(state);
382 }
383
384 #[inline]
385 fn d_rounds(state: &mut State) {
386 compress!(state);
387 compress!(state);
388 compress!(state);
389 compress!(state);
390 }
391}
392