safe_read/
lib.rs

1#![no_std]
2#![forbid(unsafe_code)]
3
4//! Panic-free bounded integer readers over an untrusted byte slice.
5//!
6//! Every multi-byte read returns 0 when the requested window is out of range —
7//! never a panic. This is the shared front door for every offset/length field
8//! parsed from an attacker-controllable forensic image, so each reader crate
9//! does not re-derive its own bounds-checked helpers.
10//!
11//! ```
12//! use safe_read::{le_u32, be_u16};
13//! assert_eq!(le_u32(&[0x78, 0x56, 0x34, 0x12], 0), 0x1234_5678);
14//! assert_eq!(be_u16(&[0xaa, 0x12, 0x34], 1), 0x1234);
15//! // Out of range is 0, never a panic:
16//! assert_eq!(le_u32(&[1, 2, 3], 0), 0);
17//! ```
18//!
19//! `#![no_std]` — pure slice arithmetic, no allocation.
20
21/// Define a fixed-width integer reader that returns 0 when the window at `off`
22/// is not fully in range (too short, offset past EOF, or `off + width`
23/// overflowing `usize`) — never a panic.
24macro_rules! bounded_reader {
25    ($name:ident, $ty:ty, $width:literal, $from_bytes:ident) => {
26        #[doc = concat!("Read a ", stringify!($ty), " at `off`; 0 if out of range. Never panics.")]
27        #[must_use]
28        pub fn $name(data: &[u8], off: usize) -> $ty {
29            let Some(end) = off.checked_add($width) else {
30                return 0;
31            };
32            match data.get(off..end) {
33                Some(slice) => {
34                    let mut buf = [0u8; $width];
35                    buf.copy_from_slice(slice);
36                    <$ty>::$from_bytes(buf)
37                }
38                None => 0,
39            }
40        }
41    };
42}
43
44bounded_reader!(be_u16, u16, 2, from_be_bytes);
45bounded_reader!(be_u32, u32, 4, from_be_bytes);
46bounded_reader!(be_u64, u64, 8, from_be_bytes);
47bounded_reader!(le_u16, u16, 2, from_le_bytes);
48bounded_reader!(le_u32, u32, 4, from_le_bytes);
49bounded_reader!(le_u64, u64, 8, from_le_bytes);
50
51#[cfg(test)]
52mod tests {
53    use super::{be_u16, be_u32, be_u64, le_u16, le_u32, le_u64};
54
55    #[test]
56    fn big_endian_reads_in_range() {
57        assert_eq!(be_u16(&[0x12, 0x34], 0), 0x1234);
58        assert_eq!(be_u32(&[0, 0, 1, 0], 0), 256);
59        assert_eq!(
60            be_u64(&[0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08], 0),
61            0x0102_0304_0506_0708
62        );
63    }
64
65    #[test]
66    fn little_endian_reads_in_range() {
67        assert_eq!(le_u16(&[0x34, 0x12], 0), 0x1234);
68        assert_eq!(le_u32(&[0, 1, 0, 0], 0), 256);
69        assert_eq!(
70            le_u64(&[0x08, 0x07, 0x06, 0x05, 0x04, 0x03, 0x02, 0x01], 0),
71            0x0102_0304_0506_0708
72        );
73    }
74
75    #[test]
76    fn reads_honor_offset() {
77        assert_eq!(be_u16(&[0xaa, 0x12, 0x34], 1), 0x1234);
78        assert_eq!(le_u32(&[0xff, 0xff, 0, 1, 0, 0], 2), 256);
79    }
80
81    #[test]
82    fn out_of_range_returns_zero_never_panics() {
83        // Too few bytes for the width.
84        assert_eq!(be_u32(&[1, 2, 3], 0), 0);
85        assert_eq!(be_u64(&[1, 2, 3, 4, 5, 6, 7], 0), 0);
86        // Offset within the slice but window runs past the end.
87        assert_eq!(be_u32(&[1, 2, 3, 4], 2), 0);
88        assert_eq!(le_u16(&[1, 2], 2), 0);
89        // Empty slice, offset past end.
90        assert_eq!(be_u16(&[], 0), 0);
91        assert_eq!(le_u32(&[1, 2, 3, 4], 100), 0);
92    }
93
94    #[test]
95    fn offset_overflow_returns_zero() {
96        // off + width overflowing usize must not panic.
97        assert_eq!(be_u32(&[1, 2, 3, 4], usize::MAX), 0);
98    }
99}
safe_read/lib.rs

safe_read/
lib.rs
