fbl/
canary.rs

1// Copyright 2026 The Fuchsia Authors
2//
3// Use of this source code is governed by a MIT-style
4// license that can be found in the LICENSE file or at
5// https://opensource.org/licenses/MIT
6
7/// An embeddable structure guard.
8///
9/// To use `fbl::Canary`, choose a 4-byte guard value.
10///
11/// You can use the `Canary::new()` method to instantiate a `Canary` object.
12/// The compiler will infer the magic value from the type definition.
13///
14/// ```rust
15/// struct MyStruct {
16///     canary: fbl::Canary<{ fbl::magic(b"guar") }>,
17///     // ...
18/// }
19///
20/// impl MyStruct {
21///     fn new() -> Self {
22///         MyStruct {
23///             canary: fbl::Canary::new(),
24///             // ...
25///         }
26///     }
27/// }
28/// ```
29///
30/// The canary initializes itself with the guard value during construction and
31/// checks it during destruction (on `Drop`). You can also manually check the
32/// value during the lifetime of your object by calling the `assert` method.
33///
34/// If the value is not an ASCII string, you can directly use an integer literal
35/// as the const generic parameter.
36///
37/// ```rust
38/// struct MyStruct {
39///     canary: fbl::Canary<0x12345678>,
40///     // ...
41/// }
42/// ```
43#[repr(C)]
44pub struct Canary<const MAGIC: u32> {
45    magic: u32,
46}
47
48impl<const MAGIC: u32> Canary<MAGIC> {
49    /// Create a new Canary with the specified magic value.
50    pub const fn new() -> Self {
51        Canary { magic: MAGIC }
52    }
53
54    /// Assert that the value of `magic` is as expected.
55    ///
56    /// # Panics
57    ///
58    /// Panics if `self.magic` is not the expected value.
59    pub fn assert(&self) {
60        let observed_magic = unsafe { core::ptr::read_volatile(&self.magic) };
61        if observed_magic != MAGIC {
62            canary_failed(MAGIC, observed_magic);
63        }
64    }
65
66    /// Some places have special handling of bad magic values. For these
67    /// cases, simply return whether the `magic` is correct, and let
68    /// them respond appropriately if not.
69    pub fn valid(&self) -> bool {
70        let observed_magic = unsafe { core::ptr::read_volatile(&self.magic) };
71        observed_magic == MAGIC
72    }
73}
74
75impl<const MAGIC: u32> Default for Canary<MAGIC> {
76    fn default() -> Self {
77        Self::new()
78    }
79}
80
81impl<const MAGIC: u32> Drop for Canary<MAGIC> {
82    fn drop(&mut self) {
83        self.assert();
84        unsafe {
85            core::ptr::write_volatile(&mut self.magic, 0);
86        }
87    }
88}
89
90#[cold]
91#[inline(never)]
92#[track_caller]
93fn canary_failed(expected: u32, observed: u32) -> ! {
94    panic!("Invalid canary (expt: {:08x}, got: {:08x})", expected, observed);
95}
96
97/// Function for generating canary magic values from strings
98pub const fn magic(str: &[u8; 4]) -> u32 {
99    ((str[0] as u32) << 24) | ((str[1] as u32) << 16) | ((str[2] as u32) << 8) | (str[3] as u32)
100}
101
102#[macro_export]
103macro_rules! canary {
104    ($str:literal) => {
105        $crate::Canary::<{ $crate::magic($str) }>::new()
106    };
107}
108
109#[cfg(test)]
110mod tests {
111    use super::*;
112
113    #[test]
114    fn test_canary_default() {
115        let canary: Canary<{ magic(b"test") }> = Default::default();
116        assert!(canary.valid());
117    }
118
119    #[test]
120    fn test_magic_runtime() {
121        let m = magic(b"abcd");
122        assert_eq!(m, 0x61626364);
123    }
124
125    #[test]
126    fn test_canary() {
127        let canary = canary!(b"test");
128        assert!(canary.valid());
129        canary.assert();
130    }
131
132    #[test]
133    #[should_panic(expected = "Invalid canary")]
134    fn test_canary_corruption() {
135        let mut canary = canary!(b"test");
136        // Corrupt the canary storage directly
137        unsafe {
138            core::ptr::write_volatile(&mut canary.magic, 0);
139        }
140        canary.assert();
141    }
142
143    unsafe extern "C" {
144        fn check_rust_canary(ptr: *const core::ffi::c_void, expected_magic: u32) -> bool;
145    }
146
147    #[test]
148    #[cfg_attr(miri, ignore = "miri does not support calling foreign functions")]
149    fn test_canary_ffi() {
150        const MAGIC_VAL: u32 = 0x12345678; // Must match the hardcoded value in C++ helper
151        let canary = Canary::<MAGIC_VAL>::new();
152        unsafe {
153            assert!(check_rust_canary(&canary as *const _ as *const core::ffi::c_void, MAGIC_VAL));
154        }
155    }
156}
fbl/canary.rs

fbl/
canary.rs
