seahash/
helper.rs

1//! Helper functions.
2
3/// Read a buffer smaller than 8 bytes into an integer in little-endian.
4///
5/// This assumes that `buf.len() < 8`. If this is not satisfied, the behavior is unspecified.
6#[inline(always)]
7pub fn read_int(buf: &[u8]) -> u64 {
8    // Because we want to make sure that it is register allocated, we fetch this into a variable.
9    // It will likely make no difference anyway, though.
10    let ptr = buf.as_ptr();
11
12    unsafe {
13        // Break it down to reads of integers with widths in total spanning the buffer. This minimizes
14        // the number of reads
15        match buf.len() {
16            // u8.
17            1 => *ptr as u64,
18            // u16.
19            2 => (ptr as *const u16).read_unaligned().to_le() as u64,
20            // u16 + u8.
21            3 => {
22                let a = (ptr as *const u16).read_unaligned().to_le() as u64;
23                let b = *ptr.offset(2) as u64;
24
25                a | (b << 16)
26            }
27            // u32.
28            4 => (ptr as *const u32).read_unaligned().to_le() as u64,
29            // u32 + u8.
30            5 => {
31                let a = (ptr as *const u32).read_unaligned().to_le() as u64;
32                let b = *ptr.offset(4) as u64;
33
34                a | (b << 32)
35            }
36            // u32 + u16.
37            6 => {
38                let a = (ptr as *const u32).read_unaligned().to_le() as u64;
39                let b = (ptr.offset(4) as *const u16).read_unaligned().to_le() as u64;
40
41                a | (b << 32)
42            }
43            // u32 + u16 + u8.
44            7 => {
45                let a = (ptr as *const u32).read_unaligned().to_le() as u64;
46                let b = (ptr.offset(4) as *const u16).read_unaligned().to_le() as u64;
47                let c = *ptr.offset(6) as u64;
48
49                a | (b << 32) | (c << 48)
50            }
51            _ => 0,
52        }
53    }
54}
55
56/// Read a little-endian 64-bit integer from some buffer.
57#[inline(always)]
58pub unsafe fn read_u64(ptr: *const u8) -> u64 {
59    #[cfg(target_pointer_width = "32")]
60    {
61        // We cannot be sure about the memory layout of a potentially emulated 64-bit integer, so
62        // we read it manually. If possible, the compiler should emit proper instructions.
63        let a = (ptr as *const u32).read_unaligned().to_le();
64        let b = (ptr.offset(4) as *const u32).read_unaligned().to_le();
65
66        a as u64 | ((b as u64) << 32)
67    }
68
69    #[cfg(target_pointer_width = "64")]
70    {
71        (ptr as *const u64).read_unaligned().to_le()
72    }
73}
74
75/// The diffusion function.
76///
77/// This is a bijective function emitting chaotic behavior. Such functions are used as building
78/// blocks for hash functions.
79pub const fn diffuse(mut x: u64) -> u64 {
80    // These are derived from the PCG RNG's round. Thanks to @Veedrac for proposing this. The basic
81    // idea is that we use dynamic shifts, which are determined by the input itself. The shift is
82    // chosen by the higher bits, which means that changing those flips the lower bits, which
83    // scatters upwards because of the multiplication.
84
85    x = x.wrapping_mul(0x6eed0e9da4d94a4f);
86    let a = x >> 32;
87    let b = x >> 60;
88    x ^= a >> b;
89    x = x.wrapping_mul(0x6eed0e9da4d94a4f);
90
91    x
92}
93
94/// Reverse the `diffuse` function.
95pub const fn undiffuse(mut x: u64) -> u64 {
96    // 0x2f72b4215a3d8caf is the modular multiplicative inverse of the constant used in `diffuse`.
97
98    x = x.wrapping_mul(0x2f72b4215a3d8caf);
99    let a = x >> 32;
100    let b = x >> 60;
101    x ^= a >> b;
102    x = x.wrapping_mul(0x2f72b4215a3d8caf);
103
104    x
105}
106
107#[cfg(test)]
108mod tests {
109    use super::*;
110
111    fn diffuse_test(x: u64, y: u64) {
112        assert_eq!(diffuse(x), y);
113        assert_eq!(x, undiffuse(y));
114        assert_eq!(undiffuse(diffuse(x)), x);
115    }
116
117    #[test]
118    fn read_int_() {
119        assert_eq!(read_int(&[2, 3]), 770);
120        assert_eq!(read_int(&[3, 2]), 515);
121        assert_eq!(read_int(&[3, 2, 5]), 328195);
122    }
123
124    #[test]
125    fn read_u64_() {
126        unsafe {
127            assert_eq!(read_u64([1, 0, 0, 0, 0, 0, 0, 0].as_ptr()), 1);
128            assert_eq!(read_u64([2, 1, 0, 0, 0, 0, 0, 0].as_ptr()), 258);
129        }
130    }
131
132    #[test]
133    fn diffuse_test_vectors() {
134        diffuse_test(94203824938, 17289265692384716055);
135        diffuse_test(0xDEADBEEF, 12110756357096144265);
136        diffuse_test(0, 0);
137        diffuse_test(1, 15197155197312260123);
138        diffuse_test(2, 1571904453004118546);
139        diffuse_test(3, 16467633989910088880);
140    }
141}
seahash/helper.rs

seahash/
helper.rs
