|
| 1 | +//! Streaming XXH64, the hash zstd uses for the optional frame |
| 2 | +//! `Content_Checksum`. |
| 3 | +//! |
| 4 | +//! A zstd frame whose `Content_Checksum_Flag` is set (the `zstd` CLI writes one |
| 5 | +//! by default) appends the low 32 bits of `XXH64(decompressed_content, seed=0)`, |
| 6 | +//! little-endian, after the last block. The decoder feeds every decompressed |
| 7 | +//! byte through [`Xxh64::update`] and compares [`Xxh64::digest`] against that |
| 8 | +//! trailer. |
| 9 | +//! |
| 10 | +//! This is the canonical XXH64 (Yann Collet) with seed 0; verified against the |
| 11 | +//! reference test vectors below and, end-to-end, against checksums produced by |
| 12 | +//! the `zstd` CLI. |
| 13 | +
|
| 14 | +const PRIME64_1: u64 = 0x9E37_79B1_85EB_CA87; |
| 15 | +const PRIME64_2: u64 = 0xC2B2_AE3D_27D4_EB4F; |
| 16 | +const PRIME64_3: u64 = 0x1656_67B1_9E37_79F9; |
| 17 | +const PRIME64_4: u64 = 0x85EB_CA77_C2B2_AE63; |
| 18 | +const PRIME64_5: u64 = 0x27D4_EB2F_1656_67C5; |
| 19 | + |
| 20 | +/// Running XXH64 state (seed fixed at 0, which is all zstd needs). |
| 21 | +#[derive(Clone)] |
| 22 | +pub(crate) struct Xxh64 { |
| 23 | + /// Four parallel accumulators, used once `total_len >= 32`. |
| 24 | + acc: [u64; 4], |
| 25 | + /// Total bytes consumed across all `update` calls. |
| 26 | + total_len: u64, |
| 27 | + /// Partial stripe carried between `update` calls (`0..32` valid bytes). |
| 28 | + buf: [u8; 32], |
| 29 | + buf_len: usize, |
| 30 | +} |
| 31 | + |
| 32 | +impl Xxh64 { |
| 33 | + pub(crate) fn new() -> Self { |
| 34 | + Self { |
| 35 | + acc: [ |
| 36 | + PRIME64_1.wrapping_add(PRIME64_2), |
| 37 | + PRIME64_2, |
| 38 | + 0, |
| 39 | + 0u64.wrapping_sub(PRIME64_1), |
| 40 | + ], |
| 41 | + total_len: 0, |
| 42 | + buf: [0u8; 32], |
| 43 | + buf_len: 0, |
| 44 | + } |
| 45 | + } |
| 46 | + |
| 47 | + #[inline] |
| 48 | + fn round(acc: u64, lane: u64) -> u64 { |
| 49 | + acc.wrapping_add(lane.wrapping_mul(PRIME64_2)) |
| 50 | + .rotate_left(31) |
| 51 | + .wrapping_mul(PRIME64_1) |
| 52 | + } |
| 53 | + |
| 54 | + #[inline] |
| 55 | + fn merge_round(acc: u64, lane: u64) -> u64 { |
| 56 | + let acc = acc ^ Self::round(0, lane); |
| 57 | + acc.wrapping_mul(PRIME64_1).wrapping_add(PRIME64_4) |
| 58 | + } |
| 59 | + |
| 60 | + #[inline] |
| 61 | + fn read_u64(b: &[u8]) -> u64 { |
| 62 | + u64::from_le_bytes(b[..8].try_into().unwrap()) |
| 63 | + } |
| 64 | + |
| 65 | + /// Consume one full 32-byte stripe into the four accumulators. |
| 66 | + #[inline] |
| 67 | + fn process_stripe(acc: &mut [u64; 4], stripe: &[u8]) { |
| 68 | + acc[0] = Self::round(acc[0], Self::read_u64(&stripe[0..8])); |
| 69 | + acc[1] = Self::round(acc[1], Self::read_u64(&stripe[8..16])); |
| 70 | + acc[2] = Self::round(acc[2], Self::read_u64(&stripe[16..24])); |
| 71 | + acc[3] = Self::round(acc[3], Self::read_u64(&stripe[24..32])); |
| 72 | + } |
| 73 | + |
| 74 | + /// Feed `data` into the running hash. |
| 75 | + pub(crate) fn update(&mut self, mut data: &[u8]) { |
| 76 | + self.total_len = self.total_len.wrapping_add(data.len() as u64); |
| 77 | + |
| 78 | + // Top off a partially filled stripe first. |
| 79 | + if self.buf_len > 0 { |
| 80 | + let need = 32 - self.buf_len; |
| 81 | + if data.len() < need { |
| 82 | + self.buf[self.buf_len..self.buf_len + data.len()].copy_from_slice(data); |
| 83 | + self.buf_len += data.len(); |
| 84 | + return; |
| 85 | + } |
| 86 | + let (head, rest) = data.split_at(need); |
| 87 | + self.buf[self.buf_len..].copy_from_slice(head); |
| 88 | + let buf = self.buf; |
| 89 | + Self::process_stripe(&mut self.acc, &buf); |
| 90 | + self.buf_len = 0; |
| 91 | + data = rest; |
| 92 | + } |
| 93 | + |
| 94 | + // Bulk stripes straight from the input. |
| 95 | + let mut chunks = data.chunks_exact(32); |
| 96 | + for stripe in &mut chunks { |
| 97 | + Self::process_stripe(&mut self.acc, stripe); |
| 98 | + } |
| 99 | + |
| 100 | + // Carry the trailing partial stripe. |
| 101 | + let rem = chunks.remainder(); |
| 102 | + if !rem.is_empty() { |
| 103 | + self.buf[..rem.len()].copy_from_slice(rem); |
| 104 | + self.buf_len = rem.len(); |
| 105 | + } |
| 106 | + } |
| 107 | + |
| 108 | + /// Finalize without disturbing the running state, returning the full 64-bit |
| 109 | + /// digest. zstd compares the low 32 bits. |
| 110 | + pub(crate) fn digest(&self) -> u64 { |
| 111 | + let mut h = if self.total_len >= 32 { |
| 112 | + let mut h = self.acc[0] |
| 113 | + .rotate_left(1) |
| 114 | + .wrapping_add(self.acc[1].rotate_left(7)) |
| 115 | + .wrapping_add(self.acc[2].rotate_left(12)) |
| 116 | + .wrapping_add(self.acc[3].rotate_left(18)); |
| 117 | + h = Self::merge_round(h, self.acc[0]); |
| 118 | + h = Self::merge_round(h, self.acc[1]); |
| 119 | + h = Self::merge_round(h, self.acc[2]); |
| 120 | + h = Self::merge_round(h, self.acc[3]); |
| 121 | + h |
| 122 | + } else { |
| 123 | + // Short input: only the seed-derived constant participates. |
| 124 | + PRIME64_5 |
| 125 | + }; |
| 126 | + |
| 127 | + h = h.wrapping_add(self.total_len); |
| 128 | + |
| 129 | + // Consume the leftover (< 32) bytes: 8 at a time, then 4, then 1. |
| 130 | + let mut p = &self.buf[..self.buf_len]; |
| 131 | + while p.len() >= 8 { |
| 132 | + let k1 = Self::round(0, Self::read_u64(p)); |
| 133 | + h = (h ^ k1) |
| 134 | + .rotate_left(27) |
| 135 | + .wrapping_mul(PRIME64_1) |
| 136 | + .wrapping_add(PRIME64_4); |
| 137 | + p = &p[8..]; |
| 138 | + } |
| 139 | + if p.len() >= 4 { |
| 140 | + let k = u32::from_le_bytes(p[..4].try_into().unwrap()) as u64; |
| 141 | + h = (h ^ k.wrapping_mul(PRIME64_1)) |
| 142 | + .rotate_left(23) |
| 143 | + .wrapping_mul(PRIME64_2) |
| 144 | + .wrapping_add(PRIME64_3); |
| 145 | + p = &p[4..]; |
| 146 | + } |
| 147 | + for &b in p { |
| 148 | + h = (h ^ (b as u64).wrapping_mul(PRIME64_5)) |
| 149 | + .rotate_left(11) |
| 150 | + .wrapping_mul(PRIME64_1); |
| 151 | + } |
| 152 | + |
| 153 | + // Final avalanche. |
| 154 | + h ^= h >> 33; |
| 155 | + h = h.wrapping_mul(PRIME64_2); |
| 156 | + h ^= h >> 29; |
| 157 | + h = h.wrapping_mul(PRIME64_3); |
| 158 | + h ^= h >> 32; |
| 159 | + h |
| 160 | + } |
| 161 | +} |
| 162 | + |
| 163 | +#[cfg(test)] |
| 164 | +mod tests { |
| 165 | + use super::*; |
| 166 | + |
| 167 | + fn xxh64(data: &[u8]) -> u64 { |
| 168 | + let mut h = Xxh64::new(); |
| 169 | + h.update(data); |
| 170 | + h.digest() |
| 171 | + } |
| 172 | + |
| 173 | + #[test] |
| 174 | + fn reference_vectors() { |
| 175 | + // Canonical XXH64 vectors (seed 0) from the reference implementation. |
| 176 | + assert_eq!(xxh64(b""), 0xEF46_DB37_51D8_E999); |
| 177 | + assert_eq!(xxh64(b"a"), 0xD24E_C4F1_A98C_6E5B); |
| 178 | + assert_eq!(xxh64(b"abc"), 0x44BC_2CF5_AD77_0999); |
| 179 | + // 64 bytes ⇒ exercises the multi-stripe accumulator path. |
| 180 | + let long: alloc::vec::Vec<u8> = (0..64u8).collect(); |
| 181 | + assert_eq!(xxh64(&long), 0xF7C6_7301_DB67_13F0); |
| 182 | + } |
| 183 | + |
| 184 | + #[test] |
| 185 | + fn streaming_matches_one_shot() { |
| 186 | + let data: alloc::vec::Vec<u8> = (0..250u32).map(|i| (i.wrapping_mul(37)) as u8).collect(); |
| 187 | + let one = xxh64(&data); |
| 188 | + // Feed in awkward chunk sizes that straddle stripe boundaries. |
| 189 | + for chunk in [1usize, 3, 7, 8, 16, 31, 32, 33] { |
| 190 | + let mut h = Xxh64::new(); |
| 191 | + for part in data.chunks(chunk) { |
| 192 | + h.update(part); |
| 193 | + } |
| 194 | + assert_eq!(h.digest(), one, "chunk size {chunk}"); |
| 195 | + } |
| 196 | + } |
| 197 | +} |
0 commit comments