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
122
123
124
125
126
127
128
129
130
//! v5 CRC32c self-describing-metadata verification (`xfs_verify_cksum`).
//!
//! Every v5 (and ONLY v5 — v4 has no CRCs) metadata block carries a CRC32c over
//! the whole on-disk object, with the 4-byte CRC field itself treated as zero
//! during the computation. XFS uses the Castagnoli/iSCSI polynomial and stores
//! the *complemented* result little-endian at a per-structure `cksum_offset`.
//!
//! This module is the shared verifier. It reproduces the kernel's
//! `xfs_verify_cksum(buffer, length, cksum_offset)` byte-exactly
//! (`fs/xfs/libxfs/xfs_cksum.h`): compute the CRC over the buffer with the CRC
//! field zeroed, then compare against the stored value. Verification is
//! **non-fatal** — a bad CRC never fails a parse; it is surfaced as
//! `crc_valid: Some(false)` so the `-forensic` layer can turn it into a Finding
//! (a forensic reader must still parse a tampered block and report the
//! mismatch). On a v4 (no-CRC) structure the status is `None`.
//!
//! ## CRC field offsets (VERBATIM from `fs/xfs/libxfs/xfs_format.h` +
//! `xfs_da_format.h`, confirmed against the on-disk struct layout)
//!
//! | structure | CRC field | offset | coverage length |
//! |---|---|---|---|
//! | superblock (`xfs_dsb`) | `sb_crc` | [`SB_CRC_OFF`] = 224 | sectorsize |
//! | AGF (`xfs_agf`) | `agf_crc` | [`AGF_CRC_OFF`] = 216 | sectorsize |
//! | AGI (`xfs_agi`) | `agi_crc` | [`AGI_CRC_OFF`] = 312 | sectorsize |
//! | AGFL (`xfs_agfl`) | `agfl_crc` | [`AGFL_CRC_OFF`] = 32 | sectorsize |
//! | inode v3 (`xfs_dinode`) | `di_crc` | [`DINODE_CRC_OFF`] = 100 | inodesize |
//! | dir data/block (`xfs_dir3_blk_hdr`) | `crc` | [`DIR3_DATA_CRC_OFF`] = 4 | blocksize |
//! | dir leaf/node (`xfs_da3_blkinfo`) | `crc` | [`DA3_BLKINFO_CRC_OFF`] = 12 | blocksize |
//! | bmbt long-form (`xfs_btree_block_lhdr`) | `bb_crc` | [`BMBT_CRC_OFF`] = 64 | blocksize |
//!
//! The coverage length is always the object's whole on-disk buffer (the value
//! the kernel passes as `BBTOB(bp->b_length)` to `xfs_buf_verify_cksum`), which
//! for a caller here is simply `buffer.len()` — the caller slices the exact
//! sector / inode / block.
/// `XFS_SB_CRC_OFF` — `offsetof(struct xfs_dsb, sb_crc)`.
pub const SB_CRC_OFF: usize = 224;
/// `XFS_AGF_CRC_OFF` — `offsetof(struct xfs_agf, agf_crc)`.
pub const AGF_CRC_OFF: usize = 216;
/// `XFS_AGI_CRC_OFF` — `offsetof(struct xfs_agi, agi_crc)`. The `agi_crc` sits
/// **after** the 256-byte `agi_unlinked[64]` array and the 16-byte `agi_uuid`
/// (magicnum/versionnum/seqno/length/count/root/level/freecount/newino/dirino =
/// 40 bytes, + unlinked → 296, + uuid → 312).
pub const AGI_CRC_OFF: usize = 312;
/// `XFS_AGFL_CRC_OFF` — `offsetof(struct xfs_agfl, agfl_crc)`.
pub const AGFL_CRC_OFF: usize = 32;
/// `XFS_DINODE_CRC_OFF` — `offsetof(struct xfs_dinode, di_crc)` (v3 core).
pub const DINODE_CRC_OFF: usize = 100;
/// `XFS_DIR3_DATA_CRC_OFF` — `offsetof(struct xfs_dir3_blk_hdr, crc)` (the
/// `hdr.crc` of every v5 dir data / single-block data block).
pub const DIR3_DATA_CRC_OFF: usize = 4;
/// `XFS_DIR3_LEAF_CRC_OFF` — `offsetof(struct xfs_da3_blkinfo, crc)` (the
/// `info.crc` of every v5 dir leaf / node / freeindex block: the 12-byte
/// `xfs_da_blkinfo` header precedes it).
pub const DA3_BLKINFO_CRC_OFF: usize = 12;
/// `XFS_BTREE_LBLOCK_CRC_OFF` — `offsetof(struct xfs_btree_block, bb_u.l.bb_crc)`
/// (the long-form v5 bmbt/`BMA3` block CRC, inside the 72-byte header).
pub const BMBT_CRC_OFF: usize = 64;
/// The XFS CRC32c parameters: Castagnoli polynomial, reflected in/out, init and
/// xorout `0xFFFFFFFF`. This is the `CRC_32_ISCSI` algorithm, whose final digest
/// equals the kernel's `~crc32c(~0, buffer)` — i.e. the exact value XFS stores
/// on disk (little-endian) via `xfs_end_cksum`. Constructing the `Crc` is cheap
/// (it references a static algorithm), so it is built per call.
/// Verify the XFS CRC32c of a metadata `buffer` whose 4-byte CRC field lies at
/// `crc_offset`, exactly as the kernel's `xfs_verify_cksum` does: compute the
/// CRC over the whole buffer with the CRC field treated as zero, and compare it
/// to the stored little-endian value.
///
/// Panic-free and bounds-checked: a buffer too short to hold the CRC field
/// (`crc_offset + 4 > buffer.len()`) returns `false` (verification fails)
/// rather than panicking — a truncated/hostile block is a failed check, never a
/// crash.
///
/// The XFS semantics ("zero the CRC field, then CRC the whole buffer") are
/// replicated with a scratch copy: the four bytes at `[crc_offset..crc_offset+4]`
/// are zeroed in the copy, the copy is CRC'd whole, and the result is compared
/// to the stored bytes. (A two-range split — CRC `[..crc_offset]`, then four
/// zero bytes, then `[crc_offset+4..]` — is byte-identical; the copy is chosen
/// for clarity and is bounded by the fixed metadata-object size.)
/// Compute the non-fatal CRC status for a metadata `buffer`: `Some(bool)` on a
/// v5 structure (verified via [`verify_crc`]), or `None` on a v4 structure
/// (which carries no CRC — a bad-CRC finding would be a false positive).
///
/// This is the single seam every parser uses to fill its `crc_valid` field, so
/// the v4→`None` / v5→`Some` decision lives in exactly one place.