Expand description
refs-core — a pure-Rust, from-scratch ReFS (Resilient File System) reader.
Parses the ReFS on-disk structures a forensic tool needs, starting from the
boot Volume Boot Record (VBR) and superblock. Imports as refs_core (the
bare refs crate name is taken by an unrelated third party on crates.io):
use refs_core::BootSector;.
§Reverse-engineered format — no official specification
ReFS is undocumented: Microsoft publishes no on-disk specification. Every
structural fact this reader encodes comes from third-party reverse
engineering — primarily libyal’s libfsrefs and Prade’s academic work.
Correctness is therefore Tier-2 at best for structural metadata (there is
no ground-truth forensic corpus); only file content can reach Tier-1, by
hashing against the live Windows ReFS driver. ReFS is also
version-fragmented — the layout differs materially between v1.x (Server
2012 / 8.1) and v3.x (Server 2016+/Win10+/Win11), and each Windows release
tweaks it. This reader targets v3.x and fails loud (naming the
version bytes) on any other major version rather than silently misparsing.
§Safety and robustness
This crate parses untrusted, attacker-controllable disk images. It is
#![forbid(unsafe_code)] and every integer is read through bounds-checked
little-endian helpers that yield 0/None out of range rather than panic
(the Paranoid Gatekeeper standard). ReFS is little-endian.
Modules§
- bytes
- Bounds-checked little-endian readers (the Paranoid Gatekeeper standard).
Structs§
- Boot
Sector - Parsed ReFS boot VBR / FS-recognition structure.
- Checkpoint
- The ReFS checkpoint.
- Container
Record - One parsed container record: a band’s identifier and its physical placement.
- Container
Resolver - A virtual → physical block resolver built from the physically resident metadata of a ReFS image.
- Container
Table - The ReFS container tree: a Minstore B+-tree of 160-byte container records
mapping each band to its physical cluster block number (
libfsrefs§8). - DirEntry
- One resolved directory entry: a name, its kind, its metadata, and — for a directory — the child object id to descend into.
- File
Metadata - File/directory metadata carried by a directory entry value.
- Meta
Block - A ReFS v3 self-describing metadata-block header.
- Metadata
Block Ref - A ReFS v3 self-describing metadata-block header: the four-byte block signature plus the block’s own block number.
- Minstore
Page - A parsed Minstore B+-tree page (leaf or internal/branch node).
- Minstore
Row - One
(key, value)Minstore node record, borrowing from the page buffer. - Object
Table - The ReFS object table: a Minstore B+-tree keyed by object identifier, whose values point at each object’s own Minstore tree root.
- PageRef
- A resolved object-table entry: the metadata block number of an object’s tree root.
- Superblock
- The parsed ReFS superblock (
SUPB, metadata level 0).
Enums§
- Refs
Error - Errors surfaced while parsing ReFS on-disk structures.
Constants§
- REFS_
FSRS - The file-system recognition-structure identifier
"FSRS"at boot offset 16. - REFS_
METADATA_ PAGE_ SIZE - The ReFS v3 metadata page (block) size in bytes: 16 KiB (four 4096-byte clusters), verified on the real v3.14 volume.
- REFS_
ROOT_ DIRECTORY_ ID - The well-known ReFS root-directory object identifier (
REFS_ROOT_DIRECTORY_IDin libyallibfsrefs). Later phases resolve this through the object table to reach the file tree. - REFS_
SIGNATURE - The ReFS file-system signature
"ReFS\0\0\0\0"at boot offset 3. - REFS_
SUPERBLOCK_ CLUSTER - The fixed cluster at which the primary ReFS superblock lives, counted from
the start of the volume.
30is the well-known reverse-engineered convention (byte offset30 * cluster_size;0x1e000at a 4096-byte cluster), confirmed on the minted v3.14 volume. - SUPB_
SIGNATURE - The
SUPBblock signature for the ReFS superblock (metadata level 0).
Functions§
- crc32c
- ReFS metadata-block checksum type
1: CRC-32C (Castagnoli). - crc64_
ecma - ReFS metadata-block checksum type
2: CRC-64/ECMA-182. - decompose_
virtual_ block - Decompose a ReFS virtual block number into
(container_index, offset_in_container)given the band size in clusters. - find_
by_ path - Resolve an absolute path (
"/dir/file") to(containing_directory_object_id, FileMetadata)by descending the directory B+trees from the root (0x600). - list_
dir - List the entries of the directory with object id
dir_object_idover a whole ReFS image, walking the directory B+tree from its root through any branch nodes down to the leaf pages. - parse_
directory - Parse a Ministore directory page into its directory entries.
- walk_
directory - Walk the directory B+tree rooted at metadata block
root_blockand return its entries, building the container resolver fromimage’s resident metadata. Exposed for a caller that already has the tree-root block (e.g. a forensic walker resolving the root itself) so it need not re-enter through the object table.