Skip to main content

Crate refs_core

Crate refs_core 

Source
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§

BootSector
Parsed ReFS boot VBR / FS-recognition structure.
Checkpoint
The ReFS checkpoint.
ContainerRecord
One parsed container record: a band’s identifier and its physical placement.
ContainerResolver
A virtual → physical block resolver built from the physically resident metadata of a ReFS image.
ContainerTable
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.
FileMetadata
File/directory metadata carried by a directory entry value.
MetaBlock
A ReFS v3 self-describing metadata-block header.
MetadataBlockRef
A ReFS v3 self-describing metadata-block header: the four-byte block signature plus the block’s own block number.
MinstorePage
A parsed Minstore B+-tree page (leaf or internal/branch node).
MinstoreRow
One (key, value) Minstore node record, borrowing from the page buffer.
ObjectTable
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§

RefsError
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_ID in libyal libfsrefs). 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. 30 is the well-known reverse-engineered convention (byte offset 30 * cluster_size; 0x1e000 at a 4096-byte cluster), confirmed on the minted v3.14 volume.
SUPB_SIGNATURE
The SUPB block 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_id over 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_block and return its entries, building the container resolver from image’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.