1SipHash implementation for Rust
2===============================
3
4This crates implements SipHash-2-4 and SipHash-1-3 in Rust.
5
6It is based on the original implementation from rust-core and exposes the
7same API.
8
9It also implements SipHash variants returning 128-bit tags.
10
11The `sip` module implements the standard 64-bit mode, whereas the `sip128`
12module implements the 128-bit mode.
13
14Usage
15-----
16
17In `Cargo.toml`:
18
19```toml
20[dependencies]
21siphasher = "1"
22```
23
24If you want [serde](https://github.com/serde-rs/serde) support, include the feature like this:
25
26```toml
27[dependencies]
28siphasher = { version = "1", features = ["serde"] }
29```
30
3164-bit mode:
32
33```rust
34use siphasher::sip::{SipHasher, SipHasher13, SipHasher24};
35
36// one-shot:
37
38let array: &[u8] = &[1, 2, 3];
39let key: &[u8; 16] = &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16];
40let hasher = SipHasher13::new_with_key(key);
41let h = hasher.hash(array);
42
43// incremental:
44
45use core::hash::Hasher;
46
47let array1: &[u8] = &[1, 2, 3];
48let array2: &[u8] = &[4, 5, 6];
49let key: &[u8; 16] = &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16];
50let mut hasher = SipHasher13::new_with_key(key);
51hasher.write(array1);
52hasher.write(array2);
53let h = hasher.finish();
54```
55
56128-bit mode:
57
58```rust
59use siphasher::sip128::{Hasher128, SipHasher, SipHasher13, SipHasher24};
60
61// one-shot:
62
63let array: &[u8] = &[1, 2, 3];
64let key: &[u8; 16] = &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16];
65let hasher = SipHasher13::new_with_key(key);
66let h = hasher.hash(array).as_bytes();
67
68// incremental:
69
70use core::hash::Hasher;
71
72let array1: &[u8] = &[1, 2, 3];
73let array2: &[u8] = &[4, 5, 6];
74let key: &[u8; 16] = &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16];
75let mut hasher = SipHasher13::new_with_key(key);
76hasher.write(array1);
77hasher.write(array2);
78let h = hasher.finish128().as_bytes();
79```
80
81[API documentation](https://docs.rs/siphasher/)
82-----------------------------------------------
83
84Note
85----
86
87Due to a confusing and not well documented API, methods from the `Hasher` trait of the standard library (`std::hash::Hasher`, `core::hash::Hasher`) produce non-portable results.
88
89This is not specific to SipHash, and affects all hash functions.
90
91The only safe methods in that trait are `write()` and `finish()`.
92
93It is thus recommended to use SipHash (and all other hash functions, actually) as documented above.
94