patina 21.1.1

Common types and functionality used in UEFI development.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

//! Hash utilities for Patina
//!
//! Provides hash implementations for general use across Patina components.
//!
//! ## License
//!
//! Copyright (c) Microsoft Corporation.
//!
//! SPDX-License-Identifier: Apache-2.0

use core::hash::Hasher;

/// A hasher that uses the Xorshift64* algorithm to generate a random number to xor with the input bytes.
///
/// **Note:** This hasher is not cryptographically secure. It is intended for fast, non-adversarial
/// hash-based change detection only.
///
/// [Xorshift64*](https://en.wikipedia.org/wiki/Xorshift#xorshift*)
pub struct Xorshift64starHasher {
    state: u64,
}

impl Xorshift64starHasher {
    /// Initialize the hasher with a seed.
    pub fn new(seed: u64) -> Self {
        Xorshift64starHasher { state: seed }
    }

    /// Generate a new random state.
    fn next_state(&mut self) -> u64 {
        self.state ^= self.state >> 12;
        self.state ^= self.state << 25;
        self.state ^= self.state >> 27;
        self.state = self.state.wrapping_mul(0x2545F4914F6CDD1D);
        self.state
    }
}

/// The default seed is derived from [`compile_time::unix!`], so all `Default` instances within the
/// same binary share the same seed. This means two default-constructed hashers will produce
/// identical output for identical input.
impl Default for Xorshift64starHasher {
    fn default() -> Self {
        Xorshift64starHasher::new(compile_time::unix!())
    }
}

impl Hasher for Xorshift64starHasher {
    fn finish(&self) -> u64 {
        self.state
    }

    fn write(&mut self, bytes: &[u8]) {
        for &byte in bytes {
            self.state ^= byte as u64;
            self.state = self.next_state();
        }
    }
}

#[cfg(test)]
#[coverage(off)]
mod tests {
    use super::*;

    #[test]
    fn test_different_seeds() {
        let seed1 = 12345;
        let seed2 = 54321;
        let mut hasher1 = Xorshift64starHasher::new(seed1);
        let mut hasher2 = Xorshift64starHasher::new(seed2);

        let num1 = hasher1.next_state();
        let num2 = hasher2.next_state();

        assert_ne!(num1, num2, "Random numbers should be different for different seeds");
    }

    #[test]
    fn test_same_seed() {
        let seed = 12345;
        let mut hasher1 = Xorshift64starHasher::new(seed);
        let mut hasher2 = Xorshift64starHasher::new(seed);

        let num1 = hasher1.next_state();
        let num2 = hasher2.next_state();

        assert_eq!(num1, num2, "Random numbers should be the same for the same seed");
    }

    #[test]
    fn test_default_hasher() {
        let hasher = Xorshift64starHasher::default();
        assert_ne!(hasher.state, 0, "Default hasher should have a non-zero seed");
    }

    #[test]
    fn test_write_and_finish() {
        let mut hasher1 = Xorshift64starHasher::new(42);
        let mut hasher2 = Xorshift64starHasher::new(42);

        hasher1.write(b"hello");
        hasher2.write(b"hello");
        assert_eq!(hasher1.finish(), hasher2.finish(), "Same input should produce same hash");

        let mut hasher3 = Xorshift64starHasher::new(42);
        hasher3.write(b"world");
        assert_ne!(hasher1.finish(), hasher3.finish(), "Different input should produce different hash");
    }

    #[test]
    fn test_detects_swapped_bytes() {
        // This is the key advantage over simple checksum: detecting byte swaps
        let mut hasher1 = Xorshift64starHasher::new(42);
        let mut hasher2 = Xorshift64starHasher::new(42);

        hasher1.write(&[1, 0]);
        hasher2.write(&[0, 1]);
        assert_ne!(hasher1.finish(), hasher2.finish(), "Swapped bytes should produce different hashes");
    }
}