use std::io::{Read, Seek, SeekFrom, Write};
use std::ops::ControlFlow;
use crate::bytes::get_u16;
use crate::fidelity::Synthesis;
use crate::finding::{Family, Finding, Findings, Severity};
use crate::io::{offset_of, read_exact_at};
use crate::path::is_hostile_component;
use crate::policy::MAX_PATH;
use crate::policy::{Limits, ReadPolicy};
use crate::time::{DosTimestamp, Timestamp};
use crate::tree::{Attributes, FsTree, NodeKind, TreeEntry, TreeError};
use super::charset::ShortNameCharset;
use super::geometry::{
FatLayout, FatType, MAX_CLUSTERS_FAT12, MIN_CLUSTERS_FAT16, layout_from_boot,
};
use super::ondisk::{
Attributes as DirAttributes, BootSector, BootSectorTail, DIR_ENTRY_SIZE, DirEntry, FsInfo,
LFN_CHARS_PER_ENTRY, LFN_LAST_ENTRY, LFN_MAX_ENTRIES, LfnEntry, NAME_DELETED, NAME_END,
NAME_LEADING_E5, ParseError,
};
use super::table;
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum Category {
BootSector,
InfoSector,
AllocationTable,
Directory,
}
impl Category {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Category::BootSector => "boot sector",
Category::InfoSector => "information sector",
Category::AllocationTable => "allocation table",
Category::Directory => "directory",
}
}
}
crate::naming::serialize_as_name!(Category);
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Location {
pub sector: Option<u32>,
pub cluster: Option<u32>,
pub entry: Option<u32>,
}
impl Location {
fn or(self, other: Self) -> Self {
Self {
sector: self.sector.or(other.sector),
cluster: self.cluster.or(other.cluster),
entry: self.entry.or(other.entry),
}
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Anomaly {
pub severity: Severity,
pub category: Category,
pub location: Location,
pub detail: String,
}
impl crate::Deviation for Anomaly {
fn severity(&self) -> Severity {
self.severity
}
fn to_finding(&self, unit: u32) -> Finding {
Anomaly::to_finding(self, unit)
}
}
impl Anomaly {
#[must_use]
pub fn to_finding(&self, bytes_per_sector: u32) -> Finding {
let Self {
severity,
category,
location,
detail,
} = self;
let Location {
sector,
cluster,
entry,
} = *location;
crate::finding::project(
*severity,
Family::Fat,
category.as_str(),
&[
("cluster", cluster.map(u64::from)),
("sector", sector.map(u64::from)),
("entry", entry.map(u64::from)),
],
sector.map(u64::from),
bytes_per_sector,
detail,
)
}
}
#[derive(Clone, PartialEq, Eq, Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ReadError {
#[error("i/o error: {message}")]
#[non_exhaustive]
Io {
kind: std::io::ErrorKind,
message: String,
},
#[error(transparent)]
Parse(#[from] ParseError),
#[error("{field} = {value} is not a value a FAT volume's parameter block carries")]
#[non_exhaustive]
BadBootSector {
field: &'static str,
value: u64,
},
#[error(
"a count of {clusters} clusters is FAT16 to the specification and to Linux and FAT12 \
to Windows; the two follow its chains through tables of different entry widths"
)]
#[non_exhaustive]
AmbiguousClusterCount {
clusters: u32,
},
#[error("cluster {cluster} is not a cluster this volume has")]
#[non_exhaustive]
ClusterOutOfRange {
cluster: u32,
},
#[error("sector {sector} is past the volume's {total_sectors} sectors")]
#[non_exhaustive]
SectorOutOfRange {
sector: u32,
total_sectors: u32,
},
#[error(
"the long name ending at entry {index} holds {units} UTF-16 units, past the format's 255"
)]
#[non_exhaustive]
LongNameTooLong {
index: u32,
units: usize,
},
#[error("the table entry for cluster {cluster} is {entry:#x}, which no chain may contain")]
#[non_exhaustive]
BadChainEntry {
cluster: u32,
entry: u32,
},
#[error("the chain from cluster {start} does not end within the volume's {clusters} clusters")]
#[non_exhaustive]
ChainTooLong {
start: u32,
clusters: u32,
},
#[error("a chain from cluster {start} ends before byte {read} of the {size} its entry records")]
#[non_exhaustive]
ChainTooShort {
start: u32,
size: u64,
read: u64,
},
#[error(
"file allocation table {copy} holds {other:#x} for cluster {cluster} where table 0 \
holds {first:#x}"
)]
#[non_exhaustive]
TableMismatch {
copy: u32,
cluster: u32,
first: u32,
other: u32,
},
#[error("file allocation table {copy} differs from table 0 in the padding past its last entry")]
#[non_exhaustive]
TablePaddingMismatch {
copy: u32,
},
#[error("table entry {index} is {found:#x} where the format defines {expected:#x}")]
#[non_exhaustive]
BadReservedEntry {
index: u32,
found: u32,
expected: u32,
},
#[error("the backup boot sector at sector {sector} is not a copy of sector 0")]
#[non_exhaustive]
BackupBootSectorDiffers {
sector: u32,
},
#[error("sector {sector} is named as the information sector and does not hold one")]
#[non_exhaustive]
BadInfoSector {
sector: u32,
},
#[error(
"the long name before entry {index} checksums to {found:#04x} and its short name to \
{expected:#04x}"
)]
#[non_exhaustive]
LongNameChecksum {
index: u32,
found: u8,
expected: u8,
},
#[error("the long-name entries ending at entry {index} do not form a complete run")]
#[non_exhaustive]
OrphanedLongName {
index: u32,
},
#[error("the long name at entry {index} is not well-formed UTF-16")]
#[non_exhaustive]
IllFormedLongName {
index: u32,
},
#[error("the {field} at entry {index} holds a value the encoding does not define")]
#[non_exhaustive]
MalformedTimestamp {
index: u32,
field: &'static str,
},
#[error(
"the short name at entry {index} carries byte {byte:#04x}, above ASCII, and this \
volume records no code page; name one to interpret it"
)]
#[non_exhaustive]
UninterpretedShortName {
index: u32,
byte: u8,
},
#[error("the name at entry {index} is one no directory can hold")]
#[non_exhaustive]
HostileName {
index: u32,
},
#[error("the entry at {index} records {size} bytes and no first cluster")]
#[non_exhaustive]
SizeWithoutAllocation {
index: u32,
size: u32,
},
#[error("{detail}")]
#[non_exhaustive]
BadDotEntry {
detail: String,
},
#[error("directory entry {index} follows the end marker and no reader reaches it")]
#[non_exhaustive]
EntriesAfterEnd {
index: u32,
},
#[error("a volume label entry sits at entry {index} of a directory that is not the root")]
#[non_exhaustive]
MisplacedVolumeLabel {
index: u32,
},
#[error("{count} clusters are allocated and reached by no chain, the first at {first}")]
#[non_exhaustive]
LostClusters {
count: u32,
first: u32,
},
#[error("no such path: {}", crate::escape::printable(.path))]
#[non_exhaustive]
NotFound {
path: Vec<u8>,
},
#[error("not a directory: {}", crate::escape::printable(.path))]
#[non_exhaustive]
NotADirectory {
path: Vec<u8>,
},
#[error("a file of {size} bytes exceeds the {limit}-byte read limit")]
#[non_exhaustive]
FileTooLarge {
size: u64,
limit: u64,
},
#[error("a walked path is longer than the {limit} bytes a path may be")]
#[non_exhaustive]
PathTooLong {
limit: usize,
},
#[error("the tree holds more than {limit} names")]
#[non_exhaustive]
WalkTooLarge {
limit: usize,
},
}
crate::io::io_error!(ReadError);
impl ReadError {
#[must_use]
pub fn anomaly(&self) -> Anomaly {
let at = |sector: Option<u32>, cluster: Option<u32>, entry: Option<u32>| Location {
sector,
cluster,
entry,
};
let (severity, category, location) = match self {
ReadError::Io { .. } => (
Severity::Structural,
Category::BootSector,
Location::default(),
),
ReadError::Parse(_) | ReadError::BadBootSector { .. } => (
Severity::Structural,
Category::BootSector,
at(Some(0), None, None),
),
ReadError::AmbiguousClusterCount { .. } => (
Severity::Conformance,
Category::BootSector,
at(Some(0), None, None),
),
ReadError::ClusterOutOfRange { cluster } => (
Severity::Structural,
Category::AllocationTable,
at(None, Some(*cluster), None),
),
ReadError::SectorOutOfRange { sector, .. } => (
Severity::Structural,
Category::BootSector,
at(Some(*sector), None, None),
),
ReadError::BadChainEntry { cluster, .. } => (
Severity::Structural,
Category::AllocationTable,
at(None, Some(*cluster), None),
),
ReadError::ChainTooLong { start, .. } | ReadError::ChainTooShort { start, .. } => (
Severity::Structural,
Category::AllocationTable,
at(None, Some(*start), None),
),
ReadError::TableMismatch { cluster, .. } => (
Severity::Integrity,
Category::AllocationTable,
at(None, Some(*cluster), None),
),
ReadError::TablePaddingMismatch { .. } => (
Severity::Cosmetic,
Category::AllocationTable,
Location::default(),
),
ReadError::BadReservedEntry { index, .. } => (
Severity::Conformance,
Category::AllocationTable,
at(None, Some(*index), None),
),
ReadError::BackupBootSectorDiffers { sector } => (
Severity::Conformance,
Category::BootSector,
at(Some(*sector), None, None),
),
ReadError::BadInfoSector { sector } => (
Severity::Conformance,
Category::InfoSector,
at(Some(*sector), None, None),
),
ReadError::LongNameChecksum { index, .. } | ReadError::OrphanedLongName { index } => (
Severity::Integrity,
Category::Directory,
at(None, None, Some(*index)),
),
ReadError::LongNameTooLong { index, .. } => (
Severity::Conformance,
Category::Directory,
at(None, None, Some(*index)),
),
ReadError::HostileName { index } | ReadError::SizeWithoutAllocation { index, .. } => (
Severity::Structural,
Category::Directory,
at(None, None, Some(*index)),
),
ReadError::IllFormedLongName { index }
| ReadError::UninterpretedShortName { index, .. }
| ReadError::EntriesAfterEnd { index }
| ReadError::MalformedTimestamp { index, .. }
| ReadError::MisplacedVolumeLabel { index } => (
Severity::Conformance,
Category::Directory,
at(None, None, Some(*index)),
),
ReadError::BadDotEntry { .. } => (
Severity::Conformance,
Category::Directory,
Location::default(),
),
ReadError::LostClusters { first, .. } => (
Severity::Conformance,
Category::AllocationTable,
at(None, Some(*first), None),
),
ReadError::NotFound { .. } | ReadError::NotADirectory { .. } => (
Severity::Structural,
Category::Directory,
Location::default(),
),
ReadError::FileTooLarge { .. }
| ReadError::PathTooLong { .. }
| ReadError::WalkTooLarge { .. } => (
Severity::Structural,
Category::Directory,
Location::default(),
),
};
Anomaly {
severity,
category,
location,
detail: self.to_string(),
}
}
}
impl<R: Read + Seek> crate::resolve::Resolve for Reader<R> {
type Ancestor = Node;
type Node = Node;
type Error = ReadError;
fn root_node(&mut self) -> Result<Node, ReadError> {
Ok(self.root())
}
fn ancestor_of(&self, node: &Node) -> Node {
*node
}
fn node_at(&mut self, ancestor: Node) -> Result<Node, ReadError> {
Ok(ancestor)
}
fn is_directory(&self, node: &Node) -> bool {
node.is_dir()
}
fn find_name(&mut self, dir: &Node, name: &[u8]) -> Result<Option<Node>, ReadError> {
let entries = self.read_dir(dir)?;
let mut folded = None;
for e in &entries {
if e.name == name {
return Ok(Some(e.node));
}
if folded.is_none() && e.name.eq_ignore_ascii_case(name) {
folded = Some(e.node);
}
}
Ok(folded)
}
fn not_found(&self, path: &[u8]) -> ReadError {
ReadError::NotFound {
path: path.to_vec(),
}
}
fn not_a_directory(&self, _node: &Node, path: &[u8]) -> ReadError {
ReadError::NotADirectory {
path: path.to_vec(),
}
}
}
impl<R: Read + Seek> crate::walk::Walk for Reader<R> {
type Pending = WalkEntry;
type Entry = WalkEntry;
type Key = u32;
type Error = ReadError;
fn cap(&mut self) -> usize {
self.limits.max_walk_entries.min(self.max_names())
}
fn seed(&mut self) -> Result<crate::walk::Seed<Self>, ReadError> {
let root = self.root();
let occupied = match root.storage {
Storage::Chain(start) => vec![start],
Storage::None | Storage::RootRegion => Vec::new(),
};
Ok((self.walk_children(&root, &[])?, occupied))
}
fn resolve(&mut self, pending: WalkEntry) -> Result<WalkEntry, ReadError> {
Ok(pending)
}
fn descend_key(&self, entry: &WalkEntry) -> Option<u32> {
if !entry.node.is_dir() {
return None;
}
match entry.node.storage {
Storage::Chain(start) => Some(start),
Storage::None | Storage::RootRegion => None,
}
}
fn children(&mut self, entry: &WalkEntry) -> Result<Vec<WalkEntry>, ReadError> {
self.walk_children(&entry.node, &entry.path)
}
fn too_large(limit: usize) -> ReadError {
ReadError::WalkTooLarge { limit }
}
}
impl From<ReadError> for TreeError {
fn from(err: ReadError) -> Self {
match err {
ReadError::Io { kind, message } => TreeError::Io { kind, message },
ReadError::FileTooLarge { .. }
| ReadError::PathTooLong { .. }
| ReadError::WalkTooLarge { .. } => TreeError::LimitExceeded {
family: Family::Fat,
detail: err.to_string(),
},
other => TreeError::Malformed {
family: Family::Fat,
detail: other.to_string(),
},
}
}
}
pub type ScanReport = crate::ScanReport<Anomaly>;
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Storage {
None,
Chain(u32),
RootRegion,
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Times {
pub create: Timestamp,
pub access: Timestamp,
pub modify: Timestamp,
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Node {
pub storage: Storage,
pub attributes: DirAttributes,
pub size: u32,
pub times: Option<Times>,
}
impl Node {
#[must_use]
pub const fn is_dir(&self) -> bool {
self.attributes.contains(DirAttributes::DIRECTORY)
|| matches!(self.storage, Storage::RootRegion)
}
#[must_use]
pub const fn is_volume_label(&self) -> bool {
!self.attributes.contains(DirAttributes::DIRECTORY)
&& self.attributes.contains(DirAttributes::VOLUME_ID)
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Entry {
pub name: Vec<u8>,
pub short_name: Vec<u8>,
pub has_long_name: bool,
pub node: Node,
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct WalkEntry {
pub path: Vec<u8>,
pub node: Node,
}
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
#[non_exhaustive]
pub struct OpenOptions {
pub common: crate::OpenOptions,
pub charset: ShortNameCharset,
}
impl OpenOptions {
#[must_use]
pub const fn new() -> Self {
Self {
common: crate::OpenOptions::new(),
charset: ShortNameCharset::Verbatim,
}
}
#[must_use]
pub const fn base(mut self, base: u64) -> Self {
self.common = self.common.base(base);
self
}
#[must_use]
pub const fn policy(mut self, policy: ReadPolicy) -> Self {
self.common = self.common.policy(policy);
self
}
#[must_use]
pub const fn limits(mut self, limits: Limits) -> Self {
self.common = self.common.limits(limits);
self
}
#[must_use]
pub const fn common(mut self, common: crate::OpenOptions) -> Self {
self.common = common;
self
}
#[must_use]
pub const fn charset(mut self, charset: ShortNameCharset) -> Self {
self.charset = charset;
self
}
}
pub struct Reader<R> {
src: R,
base: u64,
boot: BootSector,
layout: FatLayout,
policy: ReadPolicy,
limits: Limits,
charset: ShortNameCharset,
open_anomalies: Vec<Anomaly>,
fat_window: Option<(u32, Vec<u8>)>,
chain_cursor: Option<(u32, u64, u32)>,
}
enum OnDeviation<'a> {
Policy(ReadPolicy),
Collect(&'a mut Findings<Anomaly>),
}
impl OnDeviation<'_> {
fn record(&mut self, at: Location, err: ReadError) -> Result<(), ReadError> {
match self {
OnDeviation::Policy(policy) => {
if policy.is_fatal(err.anomaly().severity) {
Err(err)
} else {
Ok(())
}
}
OnDeviation::Collect(findings) => {
let mut anomaly = err.anomaly();
anomaly.location = anomaly.location.or(at);
findings.push(anomaly);
Ok(())
}
}
}
}
impl<R: Read + Seek> Reader<R> {
pub fn open(src: R) -> Result<Self, ReadError> {
Self::open_with(src, &OpenOptions::new())
}
pub fn open_with(mut src: R, options: &OpenOptions) -> Result<Self, ReadError> {
let end = src.seek(SeekFrom::End(0))?;
let available = end.saturating_sub(options.common.base);
let sector = read_exact_at(&mut src, options.common.base, BootSector::SIZE)?;
let boot = BootSector::read_from(§or)?;
let layout = layout_from_boot(&boot, available).map_err(|d| ReadError::BadBootSector {
field: d.field,
value: d.value,
})?;
let mut open_anomalies = Vec::new();
if layout.fat_type == FatType::Fat16
&& layout.clusters > MAX_CLUSTERS_FAT12
&& layout.clusters < MIN_CLUSTERS_FAT16
{
let err = ReadError::AmbiguousClusterCount {
clusters: layout.clusters,
};
if options.common.policy.is_fatal(err.anomaly().severity) {
return Err(err);
}
open_anomalies.push(err.anomaly());
}
Ok(Self {
src,
base: options.common.base,
boot,
layout,
policy: options.common.policy,
limits: options.common.limits,
charset: options.charset,
open_anomalies,
fat_window: None,
chain_cursor: None,
})
}
#[must_use]
pub const fn layout(&self) -> &FatLayout {
&self.layout
}
#[must_use]
pub const fn boot_sector(&self) -> &BootSector {
&self.boot
}
#[must_use]
pub const fn fat_type(&self) -> FatType {
self.layout.fat_type
}
#[must_use]
pub const fn policy(&self) -> ReadPolicy {
self.policy
}
#[must_use]
pub const fn charset(&self) -> ShortNameCharset {
self.charset
}
#[must_use]
pub fn root(&self) -> Node {
let storage = match self.layout.fat32 {
Some(f) => Storage::Chain(f.root_cluster),
None => Storage::RootRegion,
};
Node {
storage,
attributes: DirAttributes::DIRECTORY,
size: 0,
times: None,
}
}
pub fn info_sector(&mut self) -> Result<Option<FsInfo>, ReadError> {
let Some(fat32) = self.layout.fat32 else {
return Ok(None);
};
let sector = u32::from(fat32.fs_info_sector);
let bytes = self.read_sectors(sector, 1)?;
match FsInfo::read_from(&bytes) {
Ok(info) => Ok(Some(info)),
Err(_) => Err(ReadError::BadInfoSector { sector }),
}
}
pub fn volume_label(&mut self) -> Result<Option<Vec<u8>>, ReadError> {
let root = self.root();
let mut found = None;
self.for_each_slot::<ReadError>(&root, |_, slot| {
let first = slot.entry.name[0];
if first == NAME_END {
return Ok(ControlFlow::Break(()));
}
if first == NAME_DELETED {
return Ok(ControlFlow::Continue(()));
}
if slot.entry.attributes.contains(DirAttributes::VOLUME_ID)
&& !slot.entry.attributes.is_long_name()
&& !slot.entry.attributes.contains(DirAttributes::DIRECTORY)
{
found = Some(slot.entry.name);
return Ok(ControlFlow::Break(()));
}
Ok(ControlFlow::Continue(()))
})?;
if let Some(name) = found {
return Ok(Some(self.charset.decode(&volume_label(&name))));
}
let stored = match self.boot.tail {
BootSectorTail::Fat1216 { volume } | BootSectorTail::Fat32 { volume, .. } => {
volume.label
}
};
if stored == super::ondisk::VolumeInfo::NO_NAME {
return Ok(None);
}
let trimmed = volume_label(&stored);
if trimmed.is_empty() {
return Ok(None);
}
Ok(Some(self.charset.decode(&trimmed)))
}
fn sector_offset(&self, sector: u32) -> Option<u64> {
offset_of(
self.base,
u64::from(sector),
u64::from(self.layout.bytes_per_sector),
)
}
fn read_sectors(&mut self, first: u32, count: u32) -> Result<Vec<u8>, ReadError> {
let out_of_range = || ReadError::SectorOutOfRange {
sector: first,
total_sectors: self.layout.total_sectors,
};
let end = first
.checked_add(count)
.filter(|end| *end <= self.layout.total_sectors)
.ok_or_else(out_of_range)?;
debug_assert!(end <= self.layout.total_sectors);
let offset = self.sector_offset(first).ok_or_else(out_of_range)?;
let len = count as usize * self.layout.bytes_per_sector as usize;
Ok(read_exact_at(&mut self.src, offset, len)?)
}
const fn table_window_sectors(&self, sector_in_table: u32) -> u32 {
if sector_in_table.saturating_add(1) < self.layout.fat_sectors {
2
} else {
1
}
}
fn table_entry(&mut self, cluster: u32) -> Result<u32, ReadError> {
let fat_type = self.layout.fat_type;
if cluster >= self.layout.max_table_entries() {
return Err(ReadError::ClusterOutOfRange { cluster });
}
let copy = self.active_fat();
let offset = table::entry_offset(fat_type, cluster);
let bytes_per_sector = u64::from(self.layout.bytes_per_sector);
let sector_in_table = u32::try_from(offset / bytes_per_sector)
.map_err(|_| ReadError::ClusterOutOfRange { cluster })?;
let within = (offset % bytes_per_sector) as usize;
let start = self
.layout
.fat_start_sector(copy)
.ok_or(ReadError::ClusterOutOfRange { cluster })?;
let sector = start
.checked_add(sector_in_table)
.ok_or(ReadError::ClusterOutOfRange { cluster })?;
let window_sectors = self.table_window_sectors(sector_in_table);
let need_reload = match &self.fat_window {
Some((at, buf)) => {
*at != sector || buf.len() < window_sectors as usize * bytes_per_sector as usize
}
None => true,
};
if need_reload {
let buf = self.read_sectors(sector, window_sectors)?;
self.fat_window = Some((sector, buf));
}
let (_, buf) = self.fat_window.as_ref().expect("just loaded");
table::read_entry(fat_type, &buf[within..], 0).map_or(
Err(ReadError::ClusterOutOfRange { cluster }),
|raw| {
if fat_type == FatType::Fat12 && cluster & 1 == 1 {
let pair = u32::from(get_u16(buf, within));
Ok(pair >> 4)
} else {
Ok(raw)
}
},
)
}
fn next_cluster(&mut self, cluster: u32) -> Result<Option<u32>, ReadError> {
let fat_type = self.layout.fat_type;
let entry = self.table_entry(cluster)?;
if table::is_end_of_chain(fat_type, entry) {
return Ok(None);
}
if !table::is_cluster(fat_type, entry) {
return Err(ReadError::BadChainEntry { cluster, entry });
}
if entry - 2 >= self.layout.clusters {
return Err(ReadError::ClusterOutOfRange { cluster: entry });
}
Ok(Some(entry))
}
fn cluster_at(&mut self, start: u32, index: u64) -> Result<Option<u32>, ReadError> {
let (mut at, mut current) = match self.chain_cursor {
Some((cursor_start, cursor_index, cursor_cluster))
if cursor_start == start && cursor_index <= index =>
{
(cursor_index, cursor_cluster)
}
_ => (0, start),
};
if start < 2 || start - 2 >= self.layout.clusters {
return Err(ReadError::ClusterOutOfRange { cluster: start });
}
while at < index {
match self.next_cluster(current)? {
Some(next) => {
current = next;
at += 1;
}
None => return Ok(None),
}
if at > u64::from(self.layout.clusters) {
return Err(ReadError::ChainTooLong {
start,
clusters: self.layout.clusters,
});
}
}
self.chain_cursor = Some((start, at, current));
Ok(Some(current))
}
pub fn chain(&mut self, start: u32) -> Result<Vec<u32>, ReadError> {
if start < 2 || start - 2 >= self.layout.clusters {
return Err(ReadError::ClusterOutOfRange { cluster: start });
}
let cap = self.limits.max_walk_entries;
let mut out = vec![start];
let mut current = start;
while let Some(next) = self.next_cluster(current)? {
if out.len() as u64 > u64::from(self.layout.clusters) {
return Err(ReadError::ChainTooLong {
start,
clusters: self.layout.clusters,
});
}
if out.len() >= cap {
return Err(ReadError::WalkTooLarge { limit: cap });
}
out.push(next);
current = next;
}
Ok(out)
}
fn read_cluster(&mut self, n: u32) -> Result<Vec<u8>, ReadError> {
let first = self
.layout
.cluster_start_sector(n)
.ok_or(ReadError::ClusterOutOfRange { cluster: n })?;
self.read_sectors(first, self.layout.sectors_per_cluster)
}
fn for_each_slot<E: From<ReadError>>(
&mut self,
node: &Node,
mut visit: impl FnMut(&mut Self, Slot) -> Result<ControlFlow<()>, E>,
) -> Result<(), E> {
let entries_per_sector = (self.layout.bytes_per_sector as usize / DIR_ENTRY_SIZE).max(1);
let mut index = 0u32;
let mut next = match node.storage {
Storage::None => None,
Storage::RootRegion => self
.layout
.root_dir_start_sector()
.map(|first| (first, self.layout.root_dir_sectors, None)),
Storage::Chain(start) => Some((0, 0, Some(start))),
};
let mut visited = ClusterSet::new(self.layout.clusters);
if let Storage::Chain(start) = node.storage {
visited.insert(start);
}
let mut steps = 0u64;
while let Some((mut first, mut count, cluster)) = next {
if let Some(current) = cluster {
first = self
.layout
.cluster_start_sector(current)
.ok_or(ReadError::ClusterOutOfRange { cluster: current })?;
count = self.layout.sectors_per_cluster;
}
let bytes = self.read_sectors(first, count).map_err(E::from)?;
for (i, chunk) in bytes.as_chunks::<DIR_ENTRY_SIZE>().0.iter().enumerate() {
let Ok(entry) = DirEntry::read_from(chunk) else {
continue;
};
let slot = Slot {
entry,
index,
sector: first + (i / entries_per_sector) as u32,
};
index = index.saturating_add(1);
if visit(self, slot)?.is_break() {
return Ok(());
}
}
next = match cluster {
None => None,
Some(current) => match self.next_cluster(current).map_err(E::from)? {
None => None,
Some(following) => {
steps += 1;
let repeat = !visited.insert(following);
if repeat || steps > u64::from(self.layout.clusters) {
let Storage::Chain(start) = node.storage else {
unreachable!("only a chain steps between clusters")
};
return Err(E::from(ReadError::ChainTooLong {
start,
clusters: self.layout.clusters,
}));
}
Some((0, 0, Some(following)))
}
},
};
}
Ok(())
}
pub fn read_dir(&mut self, node: &Node) -> Result<Vec<Entry>, ReadError> {
let policy = self.policy;
self.parse_dir(node, &mut OnDeviation::Policy(policy))
}
fn parse_dir(
&mut self,
node: &Node,
deviations: &mut OnDeviation<'_>,
) -> Result<Vec<Entry>, ReadError> {
if !node.is_dir() {
return Err(ReadError::NotADirectory { path: Vec::new() });
}
let is_root = matches!(node.storage, Storage::RootRegion)
|| self
.layout
.fat32
.is_some_and(|f| node.storage == Storage::Chain(f.root_cluster));
let cap = self.limits.max_walk_entries.min(self.max_names());
let charset = self.charset;
let mut out: Vec<Entry> = Vec::new();
let mut pending = LongName::default();
let mut ended = false;
let mut reported_after_end = false;
let mut last_slot = None;
self.for_each_slot::<ReadError>(node, |reader, slot| {
let index = slot.index;
let at = Location {
sector: Some(slot.sector),
cluster: None,
entry: Some(index),
};
last_slot = Some((at, index));
let entry = slot.entry;
let first = entry.name[0];
if ended {
if first != NAME_END && !reported_after_end {
deviations.record(at, ReadError::EntriesAfterEnd { index })?;
reported_after_end = true;
}
return Ok(ControlFlow::Continue(()));
}
if first == NAME_END {
if !matches!(pending.take(), LongRun::None) {
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
ended = true;
return Ok(ControlFlow::Continue(()));
}
if first == NAME_DELETED {
if !matches!(pending.take(), LongRun::None) {
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
return Ok(ControlFlow::Continue(()));
}
if entry.attributes.is_long_name() {
let lfn = LfnEntry::read_from(&raw_bytes(&entry))?;
if pending.accept(&lfn) {
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
return Ok(ControlFlow::Continue(()));
}
let run = pending.take();
let short_name = render_short(&entry.name, entry.case_flags);
if entry.attributes.contains(DirAttributes::VOLUME_ID) {
if !is_root {
deviations.record(at, ReadError::MisplacedVolumeLabel { index })?;
}
if !matches!(run, LongRun::None) {
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
return Ok(ControlFlow::Continue(()));
}
if crate::path::is_dot_entry(&short_name) {
if !matches!(run, LongRun::None) {
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
return Ok(ControlFlow::Continue(()));
}
let mut has_long_name = false;
let mut name = None;
match run {
LongRun::None => {}
LongRun::Incomplete => {
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
LongRun::Complete { units, checksum } => {
let expected = entry.lfn_checksum();
if checksum != expected {
deviations.record(
at,
ReadError::LongNameChecksum {
index,
found: checksum,
expected,
},
)?;
} else {
if units.len() > super::name::MAX_NAME_UNITS {
deviations.record(
at,
ReadError::LongNameTooLong {
index,
units: units.len(),
},
)?;
}
let (decoded, ill_formed) = decode_utf16(&units);
if ill_formed {
deviations.record(at, ReadError::IllFormedLongName { index })?;
}
has_long_name = true;
name = Some(decoded);
}
}
}
let name = match name {
Some(name) => name,
None => {
if let Some(byte) = short_name.iter().copied().find(|b| *b >= 0x80) {
let err = ReadError::UninterpretedShortName { index, byte };
if charset == ShortNameCharset::Verbatim {
deviations.record(at, err)?;
} else {
let mut anomaly = err.anomaly();
anomaly.severity = Severity::Cosmetic;
anomaly.detail = format!(
"the short name at entry {index} carries byte {byte:#04x}, \
above ASCII, read as code page {}",
charset.as_str()
);
if let OnDeviation::Collect(findings) = deviations {
anomaly.location = anomaly.location.or(at);
findings.push(anomaly);
}
}
}
charset.decode(&short_name)
}
};
if is_hostile_component(&name) {
deviations.record(at, ReadError::HostileName { index })?;
return Ok(ControlFlow::Continue(()));
}
check_times(&entry, index, at, deviations)?;
let node = node_of(&entry, reader.layout.fat_type);
if node.size != 0 && matches!(node.storage, Storage::None) {
deviations.record(
at,
ReadError::SizeWithoutAllocation {
index,
size: node.size,
},
)?;
}
if out.len() >= cap {
return Err(ReadError::WalkTooLarge { limit: cap });
}
out.push(Entry {
name,
short_name: charset.decode(&short_name),
has_long_name,
node,
});
Ok(ControlFlow::Continue(()))
})?;
if !matches!(pending.take(), LongRun::None)
&& let Some((at, index)) = last_slot
{
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
Ok(out)
}
pub fn lookup(&mut self, path: &[u8]) -> Result<Node, ReadError> {
crate::resolve::drive(self, path, true)
}
pub fn read_into(
&mut self,
node: &Node,
offset: u64,
buf: &mut [u8],
) -> Result<usize, ReadError> {
if node.is_dir() || node.is_volume_label() {
return Ok(0);
}
let Storage::Chain(start) = node.storage else {
return Ok(0);
};
let size = u64::from(node.size);
if offset >= size || buf.is_empty() {
return Ok(0);
}
let bytes_per_cluster = u64::from(self.layout.bytes_per_cluster());
let want = buf.len().min((size - offset) as usize);
let mut done = 0usize;
while done < want {
let at = offset + done as u64;
let index = at / bytes_per_cluster;
let within = (at % bytes_per_cluster) as usize;
let Some(cluster) = self.cluster_at(start, index)? else {
return Err(ReadError::ChainTooShort {
start,
size,
read: at,
});
};
let bytes = self.read_cluster(cluster)?;
let take = (bytes.len() - within).min(want - done);
buf[done..done + take].copy_from_slice(&bytes[within..within + take]);
done += take;
}
Ok(done)
}
fn whole_file_len(&self, node: &Node) -> Result<u64, ReadError> {
let size = u64::from(node.size);
if size > self.limits.max_file_bytes {
return Err(ReadError::FileTooLarge {
size,
limit: self.limits.max_file_bytes,
});
}
Ok(size)
}
pub fn read_data_to(&mut self, node: &Node, mut out: impl Write) -> Result<u64, ReadError> {
if node.is_dir() || node.is_volume_label() {
return Ok(0);
}
let size = self.whole_file_len(node)?;
let mut buf = vec![0u8; self.layout.bytes_per_cluster() as usize];
let mut done = 0u64;
while done < size {
let want = buf.len().min((size - done) as usize);
let got = self.read_into(node, done, &mut buf[..want])?;
if got == 0 {
return Err(ReadError::ChainTooShort {
start: match node.storage {
Storage::Chain(start) => start,
_ => 0,
},
size,
read: done,
});
}
out.write_all(&buf[..got])?;
done += got as u64;
}
Ok(done)
}
pub fn read_data(&mut self, node: &Node) -> Result<Vec<u8>, ReadError> {
let mut out = Vec::new();
self.read_data_to(node, &mut out)?;
Ok(out)
}
pub fn walk(&mut self) -> Result<Vec<WalkEntry>, ReadError> {
let mut out = Vec::new();
self.walk_with::<ReadError>(|_, entry| {
out.push(entry);
Ok(())
})?;
Ok(out)
}
pub fn walk_with<E: From<ReadError>>(
&mut self,
mut visit: impl FnMut(&mut Self, WalkEntry) -> Result<(), E>,
) -> Result<(), E> {
crate::walk::drive(self, |reader, entry| visit(reader, entry))
}
fn walk_children(&mut self, node: &Node, prefix: &[u8]) -> Result<Vec<WalkEntry>, ReadError> {
let mut entries = self.read_dir(node)?;
entries.sort_by(|a, b| a.name.cmp(&b.name));
let mut children = Vec::new();
for e in entries.iter().rev() {
let path = crate::walk::child_path(prefix, &e.name)
.ok_or(ReadError::PathTooLong { limit: MAX_PATH })?;
children.push(WalkEntry { path, node: e.node });
}
Ok(children)
}
fn max_names(&self) -> usize {
let root = u64::from(self.layout.root_entries);
let data = u64::from(self.layout.clusters) * u64::from(self.layout.bytes_per_cluster())
/ DIR_ENTRY_SIZE as u64;
usize::try_from(root.saturating_add(data)).unwrap_or(usize::MAX)
}
pub fn verify_tables(&mut self) -> Result<(), ReadError> {
match self.table_faults()?.into_iter().next() {
Some(err) => Err(err),
None => Ok(()),
}
}
fn table_faults(&mut self) -> Result<Vec<ReadError>, ReadError> {
let mut out = Vec::new();
if self.mirroring_disabled() || self.layout.fats < 2 {
return Ok(out);
}
let fat_type = self.layout.fat_type;
let sectors = self.layout.fat_sectors;
let bytes_per_sector = self.layout.bytes_per_sector;
let highest = self.layout.clusters + 1;
let live_bytes = table::entry_offset(fat_type, highest) + table::entry_span(fat_type);
for copy in 1..self.layout.fats {
let mut padding_only = false;
let mut found = false;
let (Some(first_start), Some(copy_start)) = (
self.layout.fat_start_sector(0),
self.layout.fat_start_sector(copy),
) else {
continue;
};
let batch = (1u32 << 20) / bytes_per_sector.max(1);
let mut s = 0u32;
while s < sectors {
let count = batch.clamp(1, sectors - s);
let a = self.read_sectors(first_start + s, count)?;
let b = self.read_sectors(copy_start + s, count)?;
if a == b {
s += count;
continue;
}
let base = u64::from(s) * u64::from(bytes_per_sector);
let at = a
.iter()
.zip(b.iter())
.position(|(x, y)| x != y)
.expect("the batches differ") as u64
+ base;
if at >= live_bytes {
padding_only = true;
s += count;
continue;
}
let (candidate, shared) = match fat_type {
FatType::Fat12 => {
let even = (at * 2 / 3) as u32;
let odd = (at % 3 == 1 && even < highest).then_some(even + 1);
(even, odd)
}
FatType::Fat16 => ((at / 2) as u32, None),
FatType::Fat32 => ((at / 4) as u32, None),
};
let mut mismatch = None;
for cluster in [Some(candidate), shared].into_iter().flatten() {
let first = self.table_entry_in(0, cluster)?;
let other = self.table_entry_in(copy, cluster)?;
if first != other {
mismatch = Some((cluster, first, other));
break;
}
}
let (cluster, first, other) = match mismatch {
Some(found) => found,
None => (
candidate,
self.table_entry_in(0, candidate)?,
self.table_entry_in(copy, candidate)?,
),
};
out.push(ReadError::TableMismatch {
copy,
cluster,
first,
other,
});
found = true;
break;
}
if !found && padding_only {
out.push(ReadError::TablePaddingMismatch { copy });
}
}
Ok(out)
}
fn table_entry_in(&mut self, index: u32, cluster: u32) -> Result<u32, ReadError> {
let fat_type = self.layout.fat_type;
if cluster >= self.layout.max_table_entries() {
return Err(ReadError::ClusterOutOfRange { cluster });
}
let offset = table::entry_offset(fat_type, cluster);
let bytes_per_sector = u64::from(self.layout.bytes_per_sector);
let sector_in_table = u32::try_from(offset / bytes_per_sector)
.map_err(|_| ReadError::ClusterOutOfRange { cluster })?;
let within = (offset % bytes_per_sector) as usize;
let first = self
.layout
.fat_start_sector(index)
.ok_or(ReadError::ClusterOutOfRange { cluster })?;
let sector = first
.checked_add(sector_in_table)
.ok_or(ReadError::ClusterOutOfRange { cluster })?;
let count = self.table_window_sectors(sector_in_table);
let bytes = self.read_sectors(sector, count)?;
let raw = table::read_entry(fat_type, &bytes[within..], 0)
.ok_or(ReadError::ClusterOutOfRange { cluster })?;
if fat_type == FatType::Fat12 && cluster & 1 == 1 {
Ok(u32::from(get_u16(&bytes, within)) >> 4)
} else {
Ok(raw)
}
}
const fn mirroring_disabled(&self) -> bool {
match self.boot.tail {
BootSectorTail::Fat32 { params, .. } => params.ext_flags & 0x0080 != 0,
BootSectorTail::Fat1216 { .. } => false,
}
}
const fn active_fat(&self) -> u32 {
match self.boot.tail {
BootSectorTail::Fat32 { params, .. } if params.ext_flags & 0x0080 != 0 => {
let index = (params.ext_flags & 0x000F) as u32;
if index < self.layout.fats { index } else { 0 }
}
_ => 0,
}
}
#[must_use]
pub fn scan(&mut self) -> ScanReport {
let mut findings = Findings::new(self.limits.max_findings);
for anomaly in self.open_anomalies.clone() {
findings.push(anomaly);
}
self.scan_reserved(&mut findings);
self.scan_tables(&mut findings);
let reached = self.scan_tree(&mut findings);
if let Some(reached) = reached {
self.scan_lost(&mut findings, &reached);
}
findings.into_report(self.layout.bytes_per_sector)
}
fn scan_reserved(&mut self, findings: &mut Findings<Anomaly>) {
let Some(fat32) = self.layout.fat32 else {
return;
};
if let BootSectorTail::Fat32 { params, .. } = self.boot.tail
&& params.version != 0
{
findings.push(Anomaly {
severity: Severity::Conformance,
category: Category::BootSector,
location: Location::default(),
detail: format!(
"BPB_FSVer is {:#06x}: zero is the only FAT32 version defined, and a \
driver refuses a volume whose version it does not know",
params.version
),
});
}
if let Some(backup) = fat32.backup_boot_sector {
let backup = u32::from(backup);
match (self.read_sectors(0, 1), self.read_sectors(backup, 1)) {
(Ok(primary), Ok(copy)) => {
if primary != copy {
findings
.push(ReadError::BackupBootSectorDiffers { sector: backup }.anomaly());
}
}
(Err(e), _) | (_, Err(e)) => findings.push(e.anomaly()),
}
}
let info_sector = u32::from(fat32.fs_info_sector);
if let Ok(bytes) = self.read_sectors(info_sector, 1)
&& let Some(low) = bytes
.get(FsInfo::TRAIL_OFFSET..FsInfo::TRAIL_OFFSET + 2)
.map(|b| get_u16(b, 0))
&& low != 0
{
findings.push(Anomaly {
severity: Severity::Cosmetic,
category: Category::InfoSector,
location: Location {
sector: Some(info_sector),
..Location::default()
},
detail: format!(
"the information sector's trailing signature carries {low:#06x} where the \
format defines two zero bytes"
),
});
}
match self.info_sector() {
Ok(Some(info)) => {
if let Some(next) = info.next_free_cluster
&& next >= self.layout.clusters + 2
{
findings.push(Anomaly {
severity: Severity::Cosmetic,
category: Category::InfoSector,
location: Location {
sector: Some(u32::from(fat32.fs_info_sector)),
cluster: Some(next),
entry: None,
},
detail: format!(
"the next-free hint names cluster {next}, which this volume does \
not have"
),
});
}
if let Some(free) = info.free_clusters
&& free > self.layout.clusters
{
findings.push(Anomaly {
severity: Severity::Cosmetic,
category: Category::InfoSector,
location: Location {
sector: Some(u32::from(fat32.fs_info_sector)),
..Location::default()
},
detail: format!(
"the free-cluster hint is {free}, more clusters than this volume's \
{}",
self.layout.clusters
),
});
}
}
Ok(None) => {}
Err(e) => findings.push(e.anomaly()),
}
}
fn scan_tables(&mut self, findings: &mut Findings<Anomaly>) {
let fat_type = self.layout.fat_type;
let expected_media = table::media_entry(fat_type, self.boot.media);
let expected_tail = table::tail_entry(fat_type);
for (index, expected) in [(0u32, expected_media), (1, expected_tail)] {
match self.table_entry(index) {
Ok(found) if found != expected => findings.push(
ReadError::BadReservedEntry {
index,
found,
expected,
}
.anomaly(),
),
Ok(_) => {}
Err(e) => findings.push(e.anomaly()),
}
}
if self.mirroring_disabled() {
let named = match self.boot.tail {
BootSectorTail::Fat32 { params, .. } => u32::from(params.ext_flags & 0x000F),
BootSectorTail::Fat1216 { .. } => 0,
};
findings.push(Anomaly {
severity: Severity::Conformance,
category: Category::AllocationTable,
location: Location::default(),
detail: format!(
"BPB_ExtFlags switches mirroring off, so only table {named} is live and \
the copies are not obliged to agree"
),
});
if named >= self.layout.fats {
findings.push(Anomaly {
severity: Severity::Integrity,
category: Category::AllocationTable,
location: Location::default(),
detail: format!(
"BPB_ExtFlags names table {named} as the live one, but the volume \
has {} — chains are resolved through table 0 instead",
self.layout.fats
),
});
}
return;
}
match self.table_faults() {
Ok(faults) => {
for fault in faults {
findings.push(fault.anomaly());
}
}
Err(e) => findings.push(e.anomaly()),
}
}
fn scan_tree(&mut self, findings: &mut Findings<Anomaly>) -> Option<ClusterSet> {
let mut reached = ClusterSet::new(self.layout.clusters);
let mut visited = ClusterSet::new(self.layout.clusters);
let mut queue = vec![(Vec::new(), self.root())];
if let Storage::Chain(start) = self.root().storage {
visited.insert(start);
}
let mut names = 0usize;
let cap = self.limits.max_walk_entries.min(self.max_names());
while let Some((path, node)) = queue.pop() {
if findings.is_full() {
return None;
}
let claimed = self.claim_chain(&node, &path, &mut reached, findings);
if node.is_dir() {
let mut deviations = OnDeviation::Collect(findings);
let entries = match self.parse_dir(&node, &mut deviations) {
Ok(entries) => entries,
Err(e @ ReadError::WalkTooLarge { .. }) => {
findings.push(e.anomaly());
return None;
}
Err(e) => {
findings.push(e.anomaly());
continue;
}
};
self.check_dots(&node, &path, findings);
for entry in entries {
names += 1;
if names > cap {
findings.push(ReadError::WalkTooLarge { limit: cap }.anomaly());
return None;
}
let mut child = path.clone();
child.push(b'/');
child.extend_from_slice(&entry.name);
let descend = match entry.node.storage {
Storage::Chain(start) if entry.node.is_dir() => visited.insert(start),
_ => false,
};
if descend || !entry.node.is_dir() {
queue.push((child, entry.node));
}
}
} else if let Some(chain_bytes) = claimed {
let size = u64::from(node.size);
let bpc = u64::from(self.layout.bytes_per_cluster());
let need = size.div_ceil(bpc.max(1)) * bpc;
if chain_bytes != need {
findings.push(Anomaly {
severity: Severity::Conformance,
category: Category::AllocationTable,
location: Location::default(),
detail: format!(
"{}: a length of {size} bytes needs {need} bytes of clusters and \
its chain holds {chain_bytes}",
crate::escape::printable(&path)
),
});
}
}
}
Some(reached)
}
fn claim_chain(
&mut self,
node: &Node,
path: &[u8],
reached: &mut ClusterSet,
findings: &mut Findings<Anomaly>,
) -> Option<u64> {
let Storage::Chain(start) = node.storage else {
return None;
};
let mut current = start;
let mut count = 0u64;
let mut own = std::collections::HashSet::new();
loop {
if !reached.insert(current) {
let detail = if own.contains(¤t) {
format!(
"{}: the chain from cluster {start} returns to cluster {current}, \
and a chain that loops never ends",
crate::escape::printable(path)
)
} else {
format!(
"{}: cluster {current} is already part of another chain",
crate::escape::printable(path)
)
};
findings.push(Anomaly {
severity: Severity::Structural,
category: Category::AllocationTable,
location: Location {
cluster: Some(current),
..Location::default()
},
detail,
});
return None;
}
own.insert(current);
count += 1;
if count > u64::from(self.layout.clusters) {
findings.push(
ReadError::ChainTooLong {
start,
clusters: self.layout.clusters,
}
.anomaly(),
);
return None;
}
match self.next_cluster(current) {
Ok(Some(next)) => current = next,
Ok(None) => break,
Err(e) => {
findings.push(e.anomaly());
return None;
}
}
}
Some(count * u64::from(self.layout.bytes_per_cluster()))
}
fn check_dots(&mut self, node: &Node, path: &[u8], findings: &mut Findings<Anomaly>) {
if path.is_empty() {
return; }
let mut first_two: [Option<[u8; 11]>; 2] = [None, None];
let read = self.for_each_slot::<ReadError>(node, |_, slot| {
let Some(cell) = first_two.get_mut(slot.index as usize) else {
return Ok(ControlFlow::Break(()));
};
*cell = Some(slot.entry.name);
Ok(if slot.index == 1 {
ControlFlow::Break(())
} else {
ControlFlow::Continue(())
})
});
if let Err(e) = read {
findings.push(e.anomaly());
return;
}
for (index, expected) in [(0usize, &b". "[..]), (1, &b".. "[..])] {
let found = first_two[index].as_ref().map(|n| &n[..]);
if found != Some(expected) {
findings.push(
ReadError::BadDotEntry {
detail: format!(
"{}: entry {index} is {} where the format requires {}",
crate::escape::printable(path),
found.map_or("absent".to_string(), |n| {
format!("\"{}\"", crate::escape::printable(n))
}),
crate::escape::printable(expected).trim_end(),
),
}
.anomaly(),
);
}
}
}
fn scan_lost(&mut self, findings: &mut Findings<Anomaly>, reached: &ClusterSet) {
let fat_type = self.layout.fat_type;
let bad = table::bad_cluster(fat_type);
let mut count = 0u32;
let mut first = None;
for cluster in 2..self.layout.clusters + 2 {
let entry = match self.table_entry(cluster) {
Ok(entry) => entry,
Err(_) => break,
};
if entry == table::FREE || entry == bad || reached.contains(cluster) {
continue;
}
count += 1;
first.get_or_insert(cluster);
}
if let Some(first) = first {
findings.push(ReadError::LostClusters { count, first }.anomaly());
}
}
}
struct Slot {
entry: DirEntry,
index: u32,
sector: u32,
}
struct ClusterSet {
bits: Vec<u64>,
clusters: u32,
}
impl ClusterSet {
fn new(clusters: u32) -> Self {
let highest = clusters as usize + 2;
Self {
bits: vec![0u64; highest.div_ceil(64)],
clusters,
}
}
fn insert(&mut self, cluster: u32) -> bool {
if cluster < 2 || cluster - 2 >= self.clusters {
return true;
}
let (word, bit) = (cluster as usize / 64, cluster as usize % 64);
let was = self.bits[word] & (1 << bit) != 0;
self.bits[word] |= 1 << bit;
!was
}
fn contains(&self, cluster: u32) -> bool {
if cluster < 2 || cluster - 2 >= self.clusters {
return false;
}
self.bits[cluster as usize / 64] & (1 << (cluster as usize % 64)) != 0
}
}
enum LongRun {
None,
Incomplete,
Complete { units: Vec<u16>, checksum: u8 },
}
#[derive(Default)]
struct LongName {
chunks: Vec<Option<[u16; LFN_CHARS_PER_ENTRY]>>,
checksum: Option<u8>,
broken: bool,
}
impl LongName {
fn clear(&mut self) {
self.chunks.clear();
self.checksum = None;
self.broken = false;
}
fn accept(&mut self, entry: &LfnEntry) -> bool {
let ordinal = usize::from(entry.order & !LFN_LAST_ENTRY);
let mut discarded = false;
if entry.order & LFN_LAST_ENTRY != 0 {
discarded = self.is_live();
self.clear();
if ordinal == 0 || ordinal > LFN_MAX_ENTRIES {
self.broken = true;
return discarded;
}
self.chunks = vec![None; ordinal];
self.checksum = Some(entry.checksum);
}
if ordinal == 0 || ordinal > self.chunks.len() || self.checksum != Some(entry.checksum) {
self.broken = true;
return discarded;
}
if self.chunks[ordinal - 1].is_some() {
self.broken = true;
return discarded;
}
self.chunks[ordinal - 1] = Some(entry.name);
discarded
}
fn is_live(&self) -> bool {
!self.chunks.is_empty() || self.broken
}
fn take(&mut self) -> LongRun {
let run = if self.chunks.is_empty() && !self.broken {
LongRun::None
} else if self.broken || self.chunks.iter().any(Option::is_none) {
LongRun::Incomplete
} else {
let mut units = Vec::with_capacity(self.chunks.len() * LFN_CHARS_PER_ENTRY);
for chunk in self.chunks.iter().flatten() {
units.extend_from_slice(chunk);
}
if let Some(end) = units.iter().position(|u| *u == 0) {
units.truncate(end);
}
match self.checksum {
Some(checksum) => LongRun::Complete { units, checksum },
None => LongRun::Incomplete,
}
};
self.clear();
run
}
}
fn raw_bytes(entry: &DirEntry) -> [u8; DIR_ENTRY_SIZE] {
let mut buf = [0u8; DIR_ENTRY_SIZE];
let _ = entry.write_to(&mut buf);
buf
}
const NT_LOWER_BASE: u8 = 0x08;
const NT_LOWER_EXT: u8 = 0x10;
fn render_short(name: &[u8; 11], case_flags: u8) -> Vec<u8> {
let fold = |bytes: &mut Vec<u8>, lower: bool| {
if lower {
bytes.make_ascii_lowercase();
}
};
let mut base = name[..8].to_vec();
while base.last() == Some(&b' ') {
base.pop();
}
if base.first() == Some(&NAME_LEADING_E5) {
base[0] = NAME_DELETED;
}
fold(&mut base, case_flags & NT_LOWER_BASE != 0);
let mut ext = name[8..].to_vec();
while ext.last() == Some(&b' ') {
ext.pop();
}
fold(&mut ext, case_flags & NT_LOWER_EXT != 0);
if ext.is_empty() {
base
} else {
base.push(b'.');
base.extend_from_slice(&ext);
base
}
}
fn volume_label(name: &[u8; 11]) -> Vec<u8> {
let mut end = name.len();
while end > 0 && (name[end - 1] == b' ' || name[end - 1] == 0) {
end -= 1;
}
let mut out = name[..end].to_vec();
if out.first() == Some(&NAME_LEADING_E5) {
out[0] = 0xE5;
}
out
}
fn decode_utf16(units: &[u16]) -> (Vec<u8>, bool) {
let mut ill_formed = false;
let text: String = char::decode_utf16(units.iter().copied())
.map(|r| {
r.unwrap_or_else(|_| {
ill_formed = true;
char::REPLACEMENT_CHARACTER
})
})
.collect();
(text.into_bytes(), ill_formed)
}
fn check_times(
entry: &DirEntry,
index: u32,
at: Location,
deviations: &mut OnDeviation<'_>,
) -> Result<(), ReadError> {
let optional = [
(
"creation time",
DosTimestamp {
date: entry.create_date,
time: entry.create_time,
tenth: entry.create_time_tenth,
},
),
(
"access time",
DosTimestamp {
date: entry.access_date,
time: 0,
tenth: 0,
},
),
];
for (field, stamp) in optional {
if stamp != DosTimestamp::default() && !stamp.is_well_formed() {
deviations.record(at, ReadError::MalformedTimestamp { index, field })?;
}
}
let write = DosTimestamp {
date: entry.write_date,
time: entry.write_time,
tenth: 0,
};
if !write.is_well_formed() {
deviations.record(
at,
ReadError::MalformedTimestamp {
index,
field: "modification time",
},
)?;
}
Ok(())
}
fn node_of(entry: &DirEntry, fat_type: FatType) -> Node {
let first = match fat_type {
FatType::Fat32 => {
(u32::from(entry.first_cluster_hi) << 16) | u32::from(entry.first_cluster_lo)
}
FatType::Fat12 | FatType::Fat16 => u32::from(entry.first_cluster_lo),
};
Node {
storage: if first < 2 {
Storage::None
} else {
Storage::Chain(first)
},
attributes: entry.attributes,
size: entry.size,
times: Some(Times {
create: DosTimestamp {
date: entry.create_date,
time: entry.create_time,
tenth: entry.create_time_tenth,
}
.decode(),
access: DosTimestamp {
date: entry.access_date,
time: 0,
tenth: 0,
}
.decode(),
modify: DosTimestamp {
date: entry.write_date,
time: entry.write_time,
tenth: 0,
}
.decode(),
}),
}
}
impl<R: Read + Seek> FsTree for Reader<R> {
type Node = Node;
fn family(&self) -> Family {
Family::Fat
}
fn max_file_bytes(&self) -> u64 {
self.limits.max_file_bytes
}
fn walk_tree<E, F>(&mut self, mut visit: F) -> Result<(), E>
where
E: From<TreeError>,
F: FnMut(&mut Self, TreeEntry<Node>) -> Result<(), E>,
{
let root = self.root();
visit(self, TreeEntry::new(Vec::new(), NodeKind::Directory, root))?;
let outcome = self.walk_with::<WalkFail<E>>(|reader, entry| {
let kind = if entry.node.is_dir() {
NodeKind::Directory
} else {
NodeKind::File {
size: u64::from(entry.node.size),
}
};
visit(reader, TreeEntry::new(entry.path, kind, entry.node)).map_err(WalkFail::Visitor)
});
match outcome {
Ok(()) => Ok(()),
Err(WalkFail::Read(e)) => Err(E::from(TreeError::from(e))),
Err(WalkFail::Tree(e)) => Err(E::from(e)),
Err(WalkFail::Visitor(e)) => Err(e),
}
}
fn stat(&mut self, node: &Node, synthesis: &Synthesis) -> Result<Attributes, TreeError> {
Ok(Attributes::from_read_only_bit(
synthesis,
node.is_dir(),
node.attributes.contains(DirAttributes::READ_ONLY),
node.times.map(|t| (t.access, t.modify)),
))
}
fn read_bytes(&mut self, node: &Node, offset: u64, buf: &mut [u8]) -> Result<usize, TreeError> {
Ok(Reader::read_into(self, node, offset, buf)?)
}
fn link_target(&mut self, _node: &Node) -> Result<Vec<u8>, TreeError> {
Err(TreeError::Malformed {
family: Family::Fat,
detail: "a FAT volume holds no symbolic links".to_string(),
})
}
}
type WalkFail<E> = crate::tree::WalkFail<ReadError, E>;
impl<E> From<ReadError> for WalkFail<E> {
fn from(err: ReadError) -> Self {
WalkFail::Read(err)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::fat::{
BootCode, ClusterSize, FatTypeRequest, FormatOptions, Image, MEDIA_REMOVABLE, PlanRequest,
ReservedSectors, VolumeLabel, format,
};
use crate::path::canonical_parts;
use crate::source::{Metadata, TreeBuilder};
use std::io::Cursor;
const TIME: Timestamp = Timestamp::from_secs(1_426_325_212);
fn options() -> FormatOptions {
FormatOptions::new(0x1234_abcd, TIME)
}
fn tree() -> TreeBuilder {
let m = |mode| Metadata::new(mode, TIME);
TreeBuilder::new()
.directory(b"/EFI".to_vec(), m(0o755))
.directory(b"/EFI/BOOT".to_vec(), m(0o755))
.file(
b"/EFI/BOOT/BOOTX64.EFI".to_vec(),
b"MZ\x90\x00".to_vec(),
m(0o644),
)
.file(b"/readme.txt".to_vec(), b"hello\n".to_vec(), m(0o644))
.file(
b"/a-long-file-name.text".to_vec(),
vec![b'x'; 5000],
m(0o644),
)
.file(
b"/a-long-file-name-two.text".to_vec(),
b"two".to_vec(),
m(0o644),
)
.file(b"/empty".to_vec(), Vec::new(), m(0o444))
}
fn image(mib: u64, request: FatTypeRequest) -> Image {
let opts = options()
.label(VolumeLabel::new("FERROSYS").expect("label"))
.plan(PlanRequest::new(0).fat_type(request));
format(tree(), mib << 20, opts).expect("format")
}
fn each_type() -> [(FatType, Image); 3] {
[
(
FatType::Fat12,
image(2, FatTypeRequest::Exactly(FatType::Fat12)),
),
(
FatType::Fat16,
image(64, FatTypeRequest::Exactly(FatType::Fat16)),
),
(
FatType::Fat32,
image(512, FatTypeRequest::Exactly(FatType::Fat32)),
),
]
}
fn reader(image: &Image) -> Reader<Cursor<&[u8]>> {
Reader::open(Cursor::new(image.as_bytes())).expect("open")
}
fn at(layout: &FatLayout, sector: u32) -> usize {
sector as usize * layout.bytes_per_sector as usize
}
#[test]
fn a_table_read_never_reaches_past_the_copy_it_is_in() {
for (_, image) in each_type() {
let r = reader(&image);
let last = r.layout.fat_sectors - 1;
assert_eq!(
r.table_window_sectors(last),
1,
"the copy's last sector has no next sector of its own"
);
assert_eq!(r.table_window_sectors(last.saturating_sub(1)), 2);
assert_eq!(r.table_window_sectors(u32::MAX), 1);
}
}
#[test]
fn the_layout_read_back_is_the_layout_planned() {
for (what, image) in each_type() {
let r = reader(&image);
assert_eq!(r.layout(), image.layout(), "{what}");
assert_eq!(r.fat_type(), what);
}
}
#[test]
fn every_name_the_writer_placed_reads_back() {
for (what, image) in each_type() {
let mut r = reader(&image);
let mut paths: Vec<Vec<u8>> = r
.walk()
.expect("walk")
.into_iter()
.map(|e| e.path)
.collect();
paths.sort();
let expected: Vec<&[u8]> = vec![
b"/EFI",
b"/EFI/BOOT",
b"/EFI/BOOT/BOOTX64.EFI",
b"/a-long-file-name-two.text",
b"/a-long-file-name.text",
b"/empty",
b"/readme.txt",
];
let got: Vec<&[u8]> = paths.iter().map(Vec::as_slice).collect();
assert_eq!(got, expected, "{what}");
}
}
#[test]
fn every_file_reads_back_byte_for_byte() {
for (what, image) in each_type() {
let mut r = reader(&image);
for (path, expected) in [
(&b"/EFI/BOOT/BOOTX64.EFI"[..], b"MZ\x90\x00".to_vec()),
(b"/readme.txt", b"hello\n".to_vec()),
(b"/a-long-file-name.text", vec![b'x'; 5000]),
(b"/a-long-file-name-two.text", b"two".to_vec()),
(b"/empty", Vec::new()),
] {
let node = r.lookup(path).unwrap_or_else(|e| {
panic!("{what}: {} not found: {e}", String::from_utf8_lossy(path))
});
assert_eq!(u64::from(node.size), expected.len() as u64, "{what}");
assert_eq!(
r.read_data(&node).expect("read"),
expected,
"{what}: {}",
String::from_utf8_lossy(path)
);
}
}
}
#[test]
fn a_multi_cluster_file_reads_the_same_whole_as_it_does_in_pieces() {
for (what, image) in each_type() {
let mut r = reader(&image);
let node = r.lookup(b"/a-long-file-name.text").expect("lookup");
let whole = r.read_data(&node).expect("whole");
for chunk in [1usize, 7, 512, 4096] {
let mut pieces = Vec::new();
let mut buf = vec![0u8; chunk];
let mut offset = 0u64;
loop {
let got = r.read_into(&node, offset, &mut buf).expect("piece");
if got == 0 {
break;
}
pieces.extend_from_slice(&buf[..got]);
offset += got as u64;
}
assert_eq!(pieces, whole, "{what}: in {chunk}-byte pieces");
}
let mut buf = [0u8; 16];
for start in (0..whole.len()).step_by(997).rev() {
let got = r
.read_into(&node, start as u64, &mut buf)
.expect("backwards");
assert_eq!(&buf[..got], &whole[start..start + got], "{what}");
}
}
}
#[test]
fn a_short_name_is_kept_beside_the_name_and_says_whether_a_long_one_was_used() {
for (what, image) in each_type() {
let mut r = reader(&image);
let root = r.root();
let entries = r.read_dir(&root).expect("read the root");
let by_name = |n: &[u8]| {
entries
.iter()
.find(|e| e.name == n)
.unwrap_or_else(|| panic!("{what}: {} absent", String::from_utf8_lossy(n)))
};
let readme = by_name(b"readme.txt");
assert!(readme.has_long_name, "{what}");
assert_eq!(readme.short_name, b"README.TXT", "{what}");
let one = by_name(b"a-long-file-name.text");
let two = by_name(b"a-long-file-name-two.text");
assert_ne!(one.short_name, two.short_name, "{what}");
let efi = r.lookup(b"/EFI/BOOT").expect("lookup");
let boot = r.read_dir(&efi).expect("read");
let payload = boot
.iter()
.find(|e| e.name == b"BOOTX64.EFI")
.expect("entry");
assert!(
!payload.has_long_name,
"{what}: a name that is its own short name took a long-name run"
);
assert_eq!(payload.short_name, b"BOOTX64.EFI");
}
}
#[test]
fn the_case_flags_are_honoured_on_reading_and_never_written() {
for (what, image) in each_type() {
let mut r = reader(&image);
let root = r.root();
r.for_each_slot::<ReadError>(&root, |_, slot| {
assert_eq!(
slot.entry.case_flags, 0,
"{what}: the writer set a reserved case flag"
);
Ok(ControlFlow::Continue(()))
})
.expect("raw");
}
assert_eq!(render_short(b"README TXT", 0), b"README.TXT");
assert_eq!(render_short(b"README TXT", NT_LOWER_BASE), b"readme.TXT");
assert_eq!(render_short(b"README TXT", NT_LOWER_EXT), b"README.txt");
assert_eq!(
render_short(b"README TXT", NT_LOWER_BASE | NT_LOWER_EXT),
b"readme.txt"
);
assert_eq!(
render_short(b"CAF\xE9 TXT", NT_LOWER_BASE),
b"caf\xE9.TXT".to_vec(),
"the flag names the base alone, and the byte above ASCII has no case"
);
}
#[test]
fn a_name_with_no_extension_keeps_no_dot() {
assert_eq!(render_short(b"EMPTY ", 0), b"EMPTY");
assert_eq!(render_short(b"A B ", 0), b"A.B");
assert_eq!(render_short(b"\x05BC ", 0), b"\xE5BC".to_vec());
}
#[test]
fn the_volume_label_comes_from_the_root_entry() {
for (what, image) in each_type() {
let mut r = reader(&image);
assert_eq!(
r.volume_label().expect("label"),
Some(b"FERROSYS".to_vec()),
"{what}"
);
let root = r.root();
let names: Vec<Vec<u8>> = r
.read_dir(&root)
.expect("read")
.into_iter()
.map(|e| e.name)
.collect();
assert!(!names.contains(&b"FERROSYS".to_vec()), "{what}");
}
}
#[test]
fn a_strict_scan_of_a_volume_this_crate_wrote_is_clean() {
for (what, image) in each_type() {
let mut r = reader(&image);
let report = r.scan();
assert!(report.is_clean(), "{what}: {:#?}", report.anomalies());
assert!(!report.has_fatal(ReadPolicy::Strict), "{what}");
r.verify_tables()
.unwrap_or_else(|e| panic!("{what}: the tables disagree: {e}"));
}
}
#[test]
fn a_strict_read_accepts_every_volume_the_writer_produces_at_every_option() {
type Variant = (&'static str, Box<dyn Fn(FormatOptions) -> FormatOptions>);
let long_code = vec![0x90u8; BootCode::MAX_BYTES_FAT32];
let mut variants: Vec<Variant> = vec![
("default", Box::new(|o: FormatOptions| o)),
(
"unlabelled",
Box::new(|mut o: FormatOptions| {
o.label = None;
o
}),
),
(
"oem name",
Box::new(|mut o: FormatOptions| {
o.oem_name = *b"MSWIN4.1";
o
}),
),
(
"hidden sectors",
Box::new(|mut o: FormatOptions| {
o.hidden_sectors = 2048;
o
}),
),
(
"volume id",
Box::new(|mut o: FormatOptions| {
o.volume_id = 0;
o
}),
),
(
"earliest time",
Box::new(|mut o: FormatOptions| {
o.time = Timestamp::from_secs(DosTimestamp::SECS_MIN);
o
}),
),
(
"latest time",
Box::new(|mut o: FormatOptions| {
o.time = Timestamp::from_secs(DosTimestamp::SECS_MAX);
o
}),
),
(
"boot code",
Box::new(move |o: FormatOptions| {
o.boot_code(BootCode::new(&long_code).expect("boot code"))
}),
),
];
let FormatOptions {
label: _,
oem_name: _,
hidden_sectors: _,
volume_id: _,
time: _,
media: _,
boot_code: _,
plan: _,
accepted_loss: _,
synthesis: _,
} = options();
for media in (0xF8u8..=0xFF).chain([MEDIA_REMOVABLE]) {
variants.push((
"media",
Box::new(move |mut o: FormatOptions| {
o.media = media;
o
}),
));
}
for (what, mib) in [
(FatType::Fat12, 2u64),
(FatType::Fat16, 64),
(FatType::Fat32, 512),
] {
for (name, vary) in &variants {
let base = options()
.label(VolumeLabel::new("FERROSYS").expect("label"))
.plan(PlanRequest::new(0).fat_type(FatTypeRequest::Exactly(what)));
let image = format(tree(), mib << 20, vary(base))
.unwrap_or_else(|e| panic!("{what} / {name}: format: {e}"));
let mut r = Reader::open(Cursor::new(image.as_bytes()))
.unwrap_or_else(|e| panic!("{what} / {name}: a strict open: {e}"));
assert_eq!(r.layout(), image.layout(), "{what} / {name}");
let report = r.scan();
assert!(
report.is_clean(),
"{what} / {name}: {:#?}",
report.anomalies()
);
}
}
}
#[test]
fn an_undersized_fat32_is_remarked_on_and_not_refused() {
let opts = options().plan(
PlanRequest::new(0)
.cluster_size(ClusterSize::Sectors(1))
.reserved_sectors(ReservedSectors::Count(32))
.fat_type(FatTypeRequest::UndersizedFat32),
);
let image = format(TreeBuilder::new(), 8 << 20, opts).expect("format");
let mut r = Reader::open(Cursor::new(image.as_bytes())).expect("a strict open");
assert_eq!(r.fat_type(), FatType::Fat32);
assert!(r.layout().clusters < crate::fat::MIN_CLUSTERS_FAT32);
let report = r.scan();
assert!(report.is_clean(), "{:#?}", report.anomalies());
}
#[test]
fn the_reader_opens_exactly_what_detection_claims() {
for (_, image) in each_type() {
let bytes = image.as_bytes();
assert!(matches!(
crate::detect(Cursor::new(bytes)),
Ok(crate::Filesystem::Fat(_))
));
assert!(Reader::open(Cursor::new(bytes)).is_ok());
}
let mut mbr = vec![0u8; 1 << 20];
mbr[510] = 0x55;
mbr[511] = 0xAA;
mbr[0..3].copy_from_slice(&[0xEB, 0x3C, 0x90]);
assert!(crate::detect(Cursor::new(&mbr)).is_err());
assert!(matches!(
Reader::open(Cursor::new(&mbr)),
Err(ReadError::BadBootSector { .. })
));
}
#[test]
fn a_volume_inside_a_larger_image_reads_at_its_own_offset() {
const BASE: u64 = 1 << 20;
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut disk = vec![0u8; BASE as usize];
disk.extend_from_slice(image.as_bytes());
assert!(Reader::open(Cursor::new(&disk)).is_err());
let mut r = Reader::open_with(Cursor::new(&disk), &OpenOptions::new().base(BASE))
.expect("open at the partition's start");
assert_eq!(r.layout(), image.layout());
assert_eq!(r.walk().expect("walk").len(), 7);
}
#[test]
fn a_lookup_finds_a_name_however_its_letters_are_cased() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut r = reader(&image);
for path in [
&b"/EFI/BOOT/BOOTX64.EFI"[..],
b"/efi/boot/bootx64.efi",
b"/EFI/boot/BootX64.efi",
b"//EFI//BOOT//BOOTX64.EFI",
b"/./EFI/BOOT/BOOTX64.EFI",
b"/EFI/BOOT/BOOTX64.EFI/",
b"EFI/BOOT/BOOTX64.EFI",
] {
let node = r
.lookup(path)
.unwrap_or_else(|e| panic!("{}: {e}", String::from_utf8_lossy(path)));
assert_eq!(node.size, 4);
assert_eq!(
crate::path::canonical_key(path).to_ascii_uppercase(),
b"EFI/BOOT/BOOTX64.EFI",
"{}: one path to a model as well as to a lookup",
String::from_utf8_lossy(path)
);
}
assert!(matches!(
r.lookup(b"/EFI/BOOT/NOPE"),
Err(ReadError::NotFound { .. })
));
assert!(matches!(
r.lookup(b"/readme.txt/deeper"),
Err(ReadError::NotADirectory { .. })
));
}
#[test]
fn a_parent_component_ascends_though_no_entry_of_that_name_is_ever_handed_back() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut r = reader(&image);
let boot = r.lookup(b"/EFI/BOOT").expect("lookup");
let listed = r.read_dir(&boot).expect("read the subdirectory");
assert!(
!listed
.iter()
.any(|e| is_hostile_component(&e.name) || is_hostile_component(&e.short_name)),
"a name no path component may carry reached a caller: {:?}",
listed.iter().map(|e| &e.name).collect::<Vec<_>>()
);
assert_eq!(listed.len(), 1);
let want = r.lookup(b"/EFI/BOOT/BOOTX64.EFI").expect("lookup");
assert_eq!(
r.lookup(b"/EFI/BOOT/../BOOT/BOOTX64.EFI")
.map(|node| node.storage),
Ok(want.storage)
);
assert_eq!(
r.lookup(b"/EFI/..").map(|n| n.storage),
Ok(r.root().storage)
);
}
#[test]
fn a_directory_holds_no_bytes_and_yields_none() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut r = reader(&image);
let dir = r.lookup(b"/EFI").expect("lookup");
assert!(dir.is_dir());
assert_eq!(r.read_data(&dir).expect("read"), Vec::<u8>::new());
let mut buf = [0u8; 32];
assert_eq!(r.read_into(&dir, 0, &mut buf).expect("read"), 0);
}
#[test]
fn the_read_limit_refuses_rather_than_shortening() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut r = Reader::open_with(
Cursor::new(image.as_bytes()),
&OpenOptions::new().limits(Limits::new().max_file_bytes(1024)),
)
.expect("open");
let node = r.lookup(b"/a-long-file-name.text").expect("lookup");
assert!(matches!(
r.read_data(&node),
Err(ReadError::FileTooLarge {
size: 5000,
limit: 1024
})
));
assert!(matches!(
r.read_data_to(&node, std::io::sink()),
Err(ReadError::FileTooLarge {
size: 5000,
limit: 1024
})
));
let mut buf = [0u8; 64];
assert_eq!(r.read_into(&node, 0, &mut buf).expect("read"), 64);
}
#[test]
fn a_time_the_encoding_does_not_define_is_named_where_the_entry_is_read() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let entry = entry_of(&image, b"EMPTY ");
let mut bytes = image.as_bytes().to_vec();
let odd = ((2035u16 - 1980) << 9) | (2 << 5) | 31;
bytes[entry + 24..entry + 26].copy_from_slice(&odd.to_le_bytes());
let err = Reader::open(Cursor::new(bytes.as_slice()))
.expect("open")
.walk()
.expect_err("a strict read refuses it");
assert!(
matches!(
err,
ReadError::MalformedTimestamp {
field: "modification time",
..
}
),
"{err}"
);
let mut bytes = image.as_bytes().to_vec();
bytes[entry + 13] = 0;
bytes[entry + 14..entry + 18].copy_from_slice(&0u32.to_le_bytes());
Reader::open(Cursor::new(bytes.as_slice()))
.expect("open")
.walk()
.expect("a field the format calls optional and absent stops no read");
let mut bytes = image.as_bytes().to_vec();
bytes[entry + 16..entry + 18].copy_from_slice(&0u16.to_le_bytes());
let err = Reader::open(Cursor::new(bytes.as_slice()))
.expect("open")
.walk()
.expect_err("a strict read refuses it");
assert!(
matches!(
err,
ReadError::MalformedTimestamp {
field: "creation time",
..
}
),
"{err}"
);
}
fn entry_of(image: &Image, name: &[u8; 11]) -> usize {
let bytes = image.as_bytes();
bytes
.as_chunks::<DIR_ENTRY_SIZE>()
.0
.iter()
.position(|slot| &slot[..11] == name)
.map(|n| n * DIR_ENTRY_SIZE)
.unwrap_or_else(|| panic!("no entry is named {}", String::from_utf8_lossy(name)))
}
#[test]
fn a_walk_bound_is_reported_rather_than_silently_shortening_the_tree() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut r = Reader::open_with(
Cursor::new(image.as_bytes()),
&OpenOptions::new().limits(Limits::new().max_walk_entries(3)),
)
.expect("open");
assert!(matches!(
r.walk(),
Err(ReadError::WalkTooLarge { limit: 3 })
));
}
fn root_chained_through_the_whole_volume() -> (Vec<u8>, FatLayout) {
let opts = options().plan(
PlanRequest::new(0)
.cluster_size(ClusterSize::Sectors(1))
.reserved_sectors(ReservedSectors::Count(32))
.fat_type(FatTypeRequest::UndersizedFat32),
);
let image = format(TreeBuilder::new(), 8 << 20, opts).expect("format");
let layout = *image.layout();
let mut bytes = image.into_bytes();
let last = layout.clusters + 1;
let table_bytes = layout.fat_sectors as usize * layout.bytes_per_sector as usize;
for copy in 0..layout.fats {
let start = at(&layout, layout.fat_start_sector(copy).expect("a table"));
let table = &mut bytes[start..start + table_bytes];
for cluster in 2..=last {
let value = if cluster == last {
table::end_of_chain(layout.fat_type)
} else {
cluster + 1
};
assert!(table::write_entry(layout.fat_type, table, cluster, value));
}
}
let mut slot = [0u8; DIR_ENTRY_SIZE];
slot[..11].copy_from_slice(b"FILLER TXT");
slot[11] = 0x20; let stamp = DosTimestamp::encode(Timestamp::from_secs(1_426_325_212)).expect("in range");
slot[22..24].copy_from_slice(&stamp.time.to_le_bytes());
slot[24..26].copy_from_slice(&stamp.date.to_le_bytes());
let data = at(&layout, layout.first_data_sector);
for chunk in bytes[data..].as_chunks_mut::<DIR_ENTRY_SIZE>().0 {
*chunk = slot;
}
(bytes, layout)
}
#[test]
fn a_directory_larger_than_the_cap_is_refused_before_it_is_gathered() {
let (bytes, layout) = root_chained_through_the_whole_volume();
assert!(
layout.clusters > 4096,
"the fixture is too small to be evidence: {} clusters",
layout.clusters
);
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().limits(Limits::new().max_walk_entries(16)),
)
.expect("open");
let root = r.root();
assert!(matches!(
r.read_dir(&root),
Err(ReadError::WalkTooLarge { limit: 16 })
));
assert!(matches!(
r.walk(),
Err(ReadError::WalkTooLarge { limit: 16 })
));
assert!(matches!(
r.chain(2),
Err(ReadError::WalkTooLarge { limit: 16 })
));
}
#[test]
fn a_scan_that_hit_the_cap_inside_one_directory_reports_nothing_lost() {
let (bytes, _) = root_chained_through_the_whole_volume();
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new()
.policy(ReadPolicy::Lenient)
.limits(Limits::new().max_walk_entries(16)),
)
.expect("open");
let report = r.scan();
assert!(
report
.anomalies()
.iter()
.any(|a| a.detail.contains("more than 16 names")),
"{:#?}",
report.anomalies()
);
assert!(
!report
.anomalies()
.iter()
.any(|a| a.detail.contains("reached by no chain")),
"{:#?}",
report.anomalies()
);
}
fn damaged(what: FatTypeRequest, damage: impl FnOnce(&mut [u8], &FatLayout)) -> ScanReport {
let image = image(64, what);
let layout = *image.layout();
let mut bytes = image.into_bytes();
damage(&mut bytes, &layout);
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
r.scan()
}
fn set_ext_flags(bytes: &mut [u8], layout: &FatLayout, flags: u16) {
let mut sectors = vec![0u32];
if let Some(backup) = layout.fat32.and_then(|f| f.backup_boot_sector) {
sectors.push(u32::from(backup));
}
for sector in sectors {
let off = at(layout, sector) + 40;
bytes[off..off + 2].copy_from_slice(&flags.to_le_bytes());
}
}
#[test]
fn a_chain_is_followed_through_the_table_the_volume_says_is_live() {
let pristine = image(512, FatTypeRequest::Exactly(FatType::Fat32));
let layout = *pristine.layout();
let want = {
let mut r = reader(&pristine);
let node = r.lookup(b"/a-long-file-name.text").expect("lookup");
r.read_data(&node).expect("read")
};
assert_eq!(want.len(), 5000, "the fixture file spans several clusters");
let names = reader(&pristine).walk().expect("walk").len();
let mut bytes = pristine.into_bytes();
let start = at(&layout, layout.fat_start_sector(0).expect("a first table"));
let len = at(&layout, layout.fat_sectors);
bytes[start..start + len].fill(0);
set_ext_flags(&mut bytes, &layout, 0x0081);
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("a strict open");
let node = r.lookup(b"/a-long-file-name.text").expect("lookup");
assert_eq!(
r.read_data(&node).expect("read through the live table"),
want,
"the bytes are the live table's, not the abandoned copy's"
);
assert_eq!(
r.walk().expect("walk").len(),
names,
"the tree is the live table's too"
);
let mut mirrored = bytes;
set_ext_flags(&mut mirrored, &layout, 0x0000);
let mut r = Reader::open(Cursor::new(mirrored.as_slice())).expect("open");
assert!(
r.lookup(b"/a-long-file-name.text").is_err(),
"with mirroring on the read goes through the emptied copy 0, which \
resolves nothing at all"
);
}
#[test]
fn the_label_is_the_live_one_and_survives_the_leading_byte_substitution() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let live = reader(&image)
.volume_label()
.expect("read")
.expect("a label");
assert_eq!(live, b"FERROSYS");
let mut bytes = image.into_bytes();
let boot = bytes
.windows(11)
.position(|w| w == b"FERROSYS ")
.expect("the boot sector's copy");
let root = bytes
.windows(11)
.rposition(|w| w == b"FERROSYS ")
.expect("the root entry");
assert_ne!(boot, root, "the two copies are two places");
bytes[boot..boot + 11].copy_from_slice(b"STALECOPY ");
bytes[root] = NAME_DELETED;
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
assert_eq!(
r.volume_label().expect("read").as_deref(),
Some(&b"STALECOPY"[..]),
"a deleted entry is not the volume's label"
);
let mut restored = bytes.clone();
restored[root] = NAME_LEADING_E5;
restored[root + 1..root + 11].copy_from_slice(b"ABEL ");
let mut r = Reader::open_with(
Cursor::new(restored.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
assert_eq!(
r.volume_label().expect("read").expect("a label")[0],
0xE5,
"the substituted leading byte is put back"
);
}
#[test]
fn an_unknown_filesystem_version_is_reported_rather_than_scanned_clean() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat32), |bytes, layout| {
let mut sectors = vec![0u32];
if let Some(backup) = layout.fat32.and_then(|f| f.backup_boot_sector) {
sectors.push(u32::from(backup));
}
for sector in sectors {
let off = at(layout, sector) + 42;
bytes[off..off + 2].copy_from_slice(&1u16.to_le_bytes());
}
});
assert!(
report
.anomalies()
.iter()
.any(|a| a.detail.contains("BPB_FSVer is 0x0001")),
"{:#?}",
report.anomalies()
);
}
#[test]
fn a_live_table_the_volume_does_not_have_is_reported_rather_than_followed_blindly() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat32), |bytes, layout| {
set_ext_flags(bytes, layout, 0x0085);
});
assert!(
report.anomalies().iter().any(|a| {
a.severity == Severity::Integrity && a.detail.contains("names table 5")
}),
"{:#?}",
report.anomalies()
);
}
#[test]
fn a_name_carrying_terminal_control_bytes_is_escaped_where_it_enters_a_finding() {
let hostile = b"\x1b[2Jred\r";
let report = damaged(FatTypeRequest::Exactly(FatType::Fat16), |bytes, _| {
let at = bytes
.windows(11)
.position(|w| w == b"BOOTX64 EFI")
.expect("the fixture's short name is on disk");
bytes[at..at + 8].copy_from_slice(hostile);
bytes[at + 28..at + 32].copy_from_slice(&999_999u32.to_le_bytes());
});
let named: Vec<&str> = report
.anomalies()
.iter()
.map(|a| a.detail.as_str())
.filter(|d| d.contains("\\x1b"))
.collect();
assert!(
!named.is_empty(),
"a finding names the entry: {:#?}",
report.anomalies()
);
for detail in report.anomalies().iter().map(|a| &a.detail) {
assert!(
!detail.chars().any(char::is_control),
"a finding carries a raw control byte: {detail:?}"
);
}
let findings = report.to_report();
for rendered in [findings.to_table(), findings.to_json()] {
assert!(
!rendered.chars().any(|c| c.is_control() && c != '\n'),
"a rendered report carries a raw control byte: {rendered:?}"
);
}
}
#[test]
fn a_table_that_disagrees_with_its_mirror_is_an_integrity_finding() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat16), |bytes, layout| {
let second = layout.fat_start_sector(1).expect("two tables");
bytes[at(layout, second) + 8] ^= 0xFF;
});
assert!(
report
.anomalies()
.iter()
.any(|a| a.severity == Severity::Integrity
&& a.category == Category::AllocationTable),
"{:#?}",
report.anomalies()
);
assert!(report.has_fatal(ReadPolicy::Strict));
}
fn fat12_with_an_even_highest_cluster() -> (Vec<u8>, FatLayout) {
for mib in 1u64..8 {
let image = image(mib, FatTypeRequest::Exactly(FatType::Fat12));
let layout = *image.layout();
if (layout.clusters + 1).is_multiple_of(2) && layout.fats >= 2 {
return (image.into_bytes(), layout);
}
}
panic!("no FAT12 fixture in range has an even highest cluster");
}
#[test]
fn a_divergence_in_the_last_fat12_entry_is_a_mismatch_and_not_padding() {
let (mut bytes, layout) = fat12_with_an_even_highest_cluster();
let highest = layout.clusters + 1;
let shared = table::entry_offset(FatType::Fat12, highest) + 1;
let second = at(&layout, layout.fat_start_sector(1).expect("two tables"));
bytes[second + shared as usize] ^= 0x01;
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
match r.verify_tables() {
Err(ReadError::TableMismatch { copy, cluster, .. }) => {
assert_eq!(copy, 1);
assert_eq!(cluster, highest);
}
other => panic!("expected a mismatch at the last entry, got {other:?}"),
}
let report = r.scan();
assert!(
report.has_fatal(ReadPolicy::Strict),
"a table that disagrees about a live entry is not a remark: {:#?}",
report.anomalies()
);
let (mut bytes, layout) = fat12_with_an_even_highest_cluster();
let past = table::entry_offset(FatType::Fat12, layout.clusters + 1) + 2;
bytes[second + past as usize] ^= 0xFF;
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
assert!(matches!(
r.verify_tables(),
Err(ReadError::TablePaddingMismatch { copy: 1 })
));
}
#[test]
fn a_divergence_in_a_shared_fat12_byte_names_the_entry_that_differs() {
let (mut bytes, layout) = fat12_with_an_even_highest_cluster();
let second = at(&layout, layout.fat_start_sector(1).expect("two tables"));
let odd = 101u32;
let shared = table::entry_offset(FatType::Fat12, odd) as usize;
assert!(odd < layout.clusters + 1, "the fixture is too small");
let before = {
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
(
r.table_entry_in(0, odd - 1).expect("even entry"),
r.table_entry_in(0, odd).expect("odd entry"),
)
};
bytes[second + shared] ^= 0x10;
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
match r.verify_tables() {
Err(ReadError::TableMismatch {
copy,
cluster,
first,
other,
}) => {
assert_eq!(copy, 1);
assert_eq!(
cluster, odd,
"the shared byte was attributed to its neighbour"
);
assert_ne!(first, other, "a mismatch printed two identical values");
assert_eq!(first, before.1);
}
other => panic!("expected a mismatch at the odd entry, got {other:?}"),
}
let (mut bytes, _) = fat12_with_an_even_highest_cluster();
bytes[second + shared] ^= 0x01;
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
match r.verify_tables() {
Err(ReadError::TableMismatch {
cluster,
first,
other,
..
}) => {
assert_eq!(cluster, odd - 1);
assert_ne!(first, other);
assert_eq!(first, before.0);
}
other => panic!("expected a mismatch at the even entry, got {other:?}"),
}
}
#[test]
fn a_long_name_whose_checksum_does_not_match_is_an_integrity_finding() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat16), |bytes, layout| {
let root = at(
layout,
layout.root_dir_start_sector().expect("a root region"),
);
for slot in 1..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
let previous = root + (slot - 1) * DIR_ENTRY_SIZE;
if bytes[off + 11] != DirAttributes::LFN.bits()
&& bytes[previous + 11] == DirAttributes::LFN.bits()
{
bytes[off] = b'Z';
return;
}
}
panic!("the fixture holds no long-name run");
});
assert!(
report
.anomalies()
.iter()
.any(|a| a.detail.contains("checksums to")),
"{:#?}",
report.anomalies()
);
}
#[test]
fn a_first_cluster_outside_the_volume_is_a_structural_finding() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat16), |bytes, layout| {
let root = at(
layout,
layout.root_dir_start_sector().expect("a root region"),
);
for slot in 0..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
let attrs = bytes[off + 11];
let size = u32::from_le_bytes(bytes[off + 28..off + 32].try_into().unwrap());
if attrs != DirAttributes::LFN.bits() && size > 0 {
bytes[off + 26..off + 28].copy_from_slice(&0xFFFEu16.to_le_bytes());
return;
}
}
panic!("the fixture holds no file entry in the root");
});
assert!(
report.worst_severity() >= Some(Severity::Structural),
"{:#?}",
report.anomalies()
);
}
#[test]
fn clusters_allocated_and_reached_by_nothing_are_reported() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat16), |bytes, layout| {
let orphan = layout.clusters;
for copy in 0..layout.fats {
let start = at(layout, layout.fat_start_sector(copy).expect("a table"));
let off = start + table::entry_offset(FatType::Fat16, orphan) as usize;
bytes[off..off + 2].copy_from_slice(&0xFFFFu16.to_le_bytes());
}
});
assert!(
report
.anomalies()
.iter()
.any(|a| a.detail.contains("reached by no chain")),
"{:#?}",
report.anomalies()
);
}
#[test]
fn an_entry_recording_a_length_and_no_first_cluster_is_named_where_it_is_read() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let entry = entry_of(&image, b"EMPTY ");
let mut bytes = image.into_bytes();
bytes[entry + 28..entry + 32].copy_from_slice(&10u32.to_le_bytes());
let err = Reader::open(Cursor::new(bytes.as_slice()))
.expect("open")
.walk()
.expect_err("a strict read refuses it");
assert!(
matches!(err, ReadError::SizeWithoutAllocation { size: 10, .. }),
"{err}"
);
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
let report = r.scan();
let found: Vec<_> = report
.anomalies()
.iter()
.filter(|a| a.detail.contains("no first cluster"))
.collect();
assert_eq!(found.len(), 1, "{:#?}", report.anomalies());
assert_eq!(found[0].severity, Severity::Structural);
assert!(!report.is_clean());
let node = r.lookup(b"/empty").expect("lookup");
assert!(matches!(
r.read_data(&node),
Err(ReadError::ChainTooShort {
start: 0,
size: 10,
read: 0
})
));
}
#[test]
fn a_backup_boot_sector_that_has_drifted_is_reported() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat32), |bytes, layout| {
let backup = layout
.fat32
.and_then(|f| f.backup_boot_sector)
.expect("a backup");
bytes[at(layout, u32::from(backup)) + 20] ^= 0xFF;
});
assert!(
report
.anomalies()
.iter()
.any(|a| a.category == Category::BootSector),
"{:#?}",
report.anomalies()
);
}
#[test]
fn the_half_of_the_information_sector_signature_nothing_explains_is_checked() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat32), |bytes, layout| {
let info = at(
layout,
u32::from(layout.fat32.expect("a FAT32 layout").fs_info_sector),
);
bytes[info + FsInfo::TRAIL_OFFSET] ^= 0x01;
});
let found: Vec<_> = report
.anomalies()
.iter()
.filter(|a| a.category == Category::InfoSector)
.collect();
assert_eq!(found.len(), 1, "{:#?}", report.anomalies());
assert_eq!(found[0].severity, Severity::Cosmetic);
assert!(found[0].detail.contains("trailing signature"));
assert!(!report.has_fatal(ReadPolicy::Strict));
let report = damaged(FatTypeRequest::Exactly(FatType::Fat32), |bytes, layout| {
let info = at(
layout,
u32::from(layout.fat32.expect("a FAT32 layout").fs_info_sector),
);
bytes[info + FsInfo::TRAIL_OFFSET + 3] ^= 0xFF;
});
assert!(report.is_clean(), "{:#?}", report.anomalies());
}
#[test]
fn a_short_name_above_ascii_is_a_conformance_deviation_until_a_page_is_named() {
let opts =
options().plan(PlanRequest::new(0).fat_type(FatTypeRequest::Exactly(FatType::Fat16)));
let m = Metadata::new(0o644, TIME);
let src = TreeBuilder::new().file(b"/README.TXT".to_vec(), b"hi\n".to_vec(), m);
let built = format(src, 64 << 20, opts).expect("format");
let layout = *built.layout();
let mut bytes = built.into_bytes();
let root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let mut placed = false;
for slot in 0..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
if &bytes[off..off + 11] == b"README TXT" {
bytes[off + 5] = 0x82;
placed = true;
break;
}
}
assert!(placed, "the fixture holds no README entry");
let mut strict = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let root_node = strict.root();
assert!(matches!(
strict.read_dir(&root_node),
Err(ReadError::UninterpretedShortName { byte: 0x82, .. })
));
let mut lenient = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let root_node = lenient.root();
let names: Vec<Vec<u8>> = lenient
.read_dir(&root_node)
.expect("read")
.into_iter()
.map(|e| e.name)
.collect();
assert!(names.contains(&b"READM\x82.TXT".to_vec()), "{names:?}");
let report = lenient.scan();
assert_eq!(
report.worst_severity(),
Some(Severity::Conformance),
"{:#?}",
report.anomalies()
);
let mut named = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().charset(ShortNameCharset::Cp437),
)
.expect("open");
let root_node = named.root();
let names: Vec<Vec<u8>> = named
.read_dir(&root_node)
.expect("a strict read, with the page named")
.into_iter()
.map(|e| e.name)
.collect();
assert!(
names.contains(&"READMé.TXT".as_bytes().to_vec()),
"{names:?}"
);
let report = named.scan();
assert_eq!(report.worst_severity(), Some(Severity::Cosmetic));
assert!(!report.has_fatal(ReadPolicy::Strict));
}
#[test]
fn a_long_name_that_is_not_well_formed_utf16_is_read_with_a_replacement() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let mut bytes = image.into_bytes();
let root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let mut placed = false;
for slot in 0..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
if bytes[off + 11] == DirAttributes::LFN.bits() && bytes[off] & !LFN_LAST_ENTRY == 1 {
bytes[off + 1..off + 3].copy_from_slice(&0xD800u16.to_le_bytes());
placed = true;
break;
}
}
assert!(placed, "the fixture holds no long-name entry");
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let root_node = r.root();
let names: Vec<Vec<u8>> = r
.read_dir(&root_node)
.expect("read")
.into_iter()
.map(|e| e.name)
.collect();
assert!(
names.iter().any(|n| n.starts_with("\u{FFFD}".as_bytes())),
"{names:?}"
);
assert!(
r.scan()
.anomalies()
.iter()
.any(|a| a.detail.contains("well-formed UTF-16"))
);
}
#[test]
fn an_orphaned_long_name_run_is_reported_however_the_run_ends() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let bytes = image.into_bytes();
let root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let short_off = (0..layout.root_entries as usize)
.map(|slot| root + slot * DIR_ENTRY_SIZE)
.find(|&off| {
bytes[off + 11] == DirAttributes::LFN.bits() && bytes[off] == LFN_LAST_ENTRY | 1
})
.map(|off| off + DIR_ENTRY_SIZE)
.expect("the fixture holds a single-entry long-name run");
let orphans_of = |edit: &dyn Fn(&mut [u8])| -> usize {
let mut edited = bytes.clone();
edit(&mut edited[short_off..short_off + DIR_ENTRY_SIZE]);
let mut r = Reader::open_with(
Cursor::new(edited.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
r.scan()
.anomalies()
.iter()
.filter(|a| a.detail.contains("do not form a complete run"))
.count()
};
assert_eq!(orphans_of(&|_| {}), 0, "the fixture is clean");
assert_eq!(
orphans_of(&|slot| slot[0] = NAME_END),
1,
"at the end marker"
);
assert_eq!(
orphans_of(&|slot| slot[0] = NAME_DELETED),
1,
"at a deleted entry"
);
assert_eq!(
orphans_of(&|slot| slot[11] = DirAttributes::VOLUME_ID.bits()),
1,
"at the volume label"
);
assert!(
orphans_of(&|slot| {
slot[0] = LFN_LAST_ENTRY | 1;
slot[11] = DirAttributes::LFN.bits();
}) >= 1,
"at a second sequence start"
);
assert_eq!(
orphans_of(&|slot| {
slot[..11].copy_from_slice(b". ");
slot[11] = DirAttributes::DIRECTORY.bits();
}),
1,
"at a dot entry"
);
}
fn root_long_name_spelling(name: &str) -> Vec<u8> {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let mut bytes = image.into_bytes();
let root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let units: Vec<u16> = name.encode_utf16().collect();
assert!(
units.len() < LFN_CHARS_PER_ENTRY,
"the name and its terminator must fit one entry"
);
for slot in 0..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
if bytes[off + 11] != DirAttributes::LFN.bits() || bytes[off] != LFN_LAST_ENTRY | 1 {
continue;
}
for i in 0..LFN_CHARS_PER_ENTRY {
let within = match i {
0..=4 => 1 + i * 2,
5..=10 => 14 + (i - 5) * 2,
_ => 28 + (i - 11) * 2,
};
let unit = match i.cmp(&units.len()) {
std::cmp::Ordering::Less => units[i],
std::cmp::Ordering::Equal => 0,
std::cmp::Ordering::Greater => 0xFFFF,
};
bytes[off + within..off + within + 2].copy_from_slice(&unit.to_le_bytes());
}
return bytes;
}
panic!("the fixture holds no single-entry long-name run");
}
fn root_short_name_of_efi(name: &[u8; 11]) -> Vec<u8> {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let mut bytes = image.into_bytes();
let root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
for slot in 0..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
if &bytes[off..off + 11] == b"EFI " {
bytes[off..off + 11].copy_from_slice(name);
return bytes;
}
}
panic!("the fixture holds no EFI entry");
}
fn assert_hostile_name_is_refused(bytes: &[u8], what: &str) {
let mut strict = Reader::open(Cursor::new(bytes)).expect("open");
let root_node = strict.root();
assert!(
matches!(
strict.read_dir(&root_node),
Err(ReadError::HostileName { .. })
),
"{what}: a strict read did not stop at it"
);
let mut lenient = Reader::open_with(
Cursor::new(bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let root_node = lenient.root();
for entry in lenient.read_dir(&root_node).expect("a lenient read") {
assert!(
!is_hostile_component(&entry.name),
"{what}: read_dir handed back {:?}",
String::from_utf8_lossy(&entry.name)
);
}
for entry in lenient.walk().expect("a lenient walk") {
for component in canonical_parts(&entry.path) {
assert!(
!is_hostile_component(component),
"{what}: the walk built {:?}",
String::from_utf8_lossy(&entry.path)
);
}
}
let report = lenient.scan();
assert!(!report.is_clean(), "{what}: the scan found nothing");
assert!(
report
.anomalies()
.iter()
.any(|a| a.severity == Severity::Structural
&& a.category == Category::Directory
&& a.detail.contains("no directory can hold")),
"{what}: {:#?}",
report.anomalies()
);
assert!(report.has_fatal(ReadPolicy::Strict), "{what}");
}
#[test]
fn a_long_name_a_directory_could_not_hold_is_refused_where_it_is_resolved() {
for name in ["..", ".", "a/b", "../etc"] {
assert_hostile_name_is_refused(&root_long_name_spelling(name), name);
}
}
#[test]
fn a_short_name_a_directory_could_not_hold_is_refused_where_it_is_resolved() {
for (name, what) in [(b"E/I ", "a separator"), (b"E\0I ", "a NUL")] {
assert_hostile_name_is_refused(&root_short_name_of_efi(name), what);
}
assert_hostile_name_is_refused(&root_short_name_of_efi(b" "), "an empty name");
}
#[cfg(feature = "tar")]
#[test]
fn an_archive_of_a_volume_holding_a_traversal_name_carries_no_traversal_member() {
let bytes = root_long_name_spelling("..");
let mut reader = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let mut archive = Vec::new();
crate::ArchiveSink::new(&mut archive)
.write_tree(&mut reader)
.expect("write the archive");
let mut members = 0usize;
for entry in tar::Archive::new(archive.as_slice())
.entries()
.expect("the archive lists its members")
{
let path = entry.expect("a member").path_bytes().to_vec();
for component in canonical_parts(&path) {
assert_ne!(
component,
b"..",
"the archive holds {:?}",
String::from_utf8_lossy(&path)
);
}
assert!(!path.contains(&0), "a member name carries a NUL");
members += 1;
}
assert!(members > 1, "the archive holds only {members} members");
}
#[test]
fn a_used_slot_past_the_end_marker_is_reported_and_never_handed_back() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let mut bytes = image.into_bytes();
let root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let mut placed = None;
for slot in 0..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
if bytes[off] == NAME_END {
let mut ghost = [0u8; DIR_ENTRY_SIZE];
ghost[..11].copy_from_slice(b"GHOST TXT");
ghost[11] = DirAttributes::ARCHIVE.bits();
let past = off + DIR_ENTRY_SIZE;
bytes[past..past + DIR_ENTRY_SIZE].copy_from_slice(&ghost);
placed = Some(slot + 1);
break;
}
}
assert!(placed.is_some(), "the fixture's root has no free slot");
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let root_node = r.root();
let names: Vec<Vec<u8>> = r
.read_dir(&root_node)
.expect("read")
.into_iter()
.map(|e| e.name)
.collect();
assert!(
!names.contains(&b"GHOST.TXT".to_vec()),
"an entry past the end marker was handed back: {names:?}"
);
assert!(
r.scan()
.anomalies()
.iter()
.any(|a| a.detail.contains("follows the end marker")),
"{:#?}",
r.scan().anomalies()
);
let mut strict = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let root_node = strict.root();
assert!(matches!(
strict.read_dir(&root_node),
Err(ReadError::EntriesAfterEnd { .. })
));
}
#[test]
fn a_scan_that_stopped_short_does_not_report_lost_clusters() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
for limits in [
Limits::new().max_walk_entries(2),
Limits::new().max_findings(1),
] {
let mut r = Reader::open_with(
Cursor::new(image.as_bytes()),
&OpenOptions::new()
.policy(ReadPolicy::Lenient)
.limits(limits),
)
.expect("open");
let report = r.scan();
assert!(
!report
.anomalies()
.iter()
.any(|a| a.detail.contains("reached by no chain")),
"a scan that stopped short reported lost clusters: {:#?}",
report.anomalies()
);
}
let mut r = Reader::open(Cursor::new(image.as_bytes())).expect("open");
assert!(r.scan().is_clean());
}
#[test]
fn a_scan_that_never_looked_is_not_a_clean_verdict() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut r = Reader::open_with(
Cursor::new(image.as_bytes()),
&OpenOptions::new()
.policy(ReadPolicy::Lenient)
.limits(Limits::new().max_findings(0)),
)
.expect("open");
let report = r.scan();
assert!(report.anomalies().is_empty());
assert!(report.is_truncated());
assert!(!report.is_clean(), "a truncated report claimed a verdict");
assert!(report.to_report().to_json().contains("\"clean\":false"));
}
#[test]
fn a_chain_that_loops_is_bounded_rather_than_followed() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let mut bytes = image.into_bytes();
let start = {
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let node = r.lookup(b"/a-long-file-name.text").expect("lookup");
match node.storage {
Storage::Chain(start) => start,
_ => panic!("the fixture's multi-cluster file owns no chain"),
}
};
for copy in 0..layout.fats {
let off = at(&layout, layout.fat_start_sector(copy).expect("a table"))
+ table::entry_offset(FatType::Fat16, start + 1) as usize;
bytes[off..off + 2].copy_from_slice(&(start as u16).to_le_bytes());
}
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
assert!(matches!(
r.chain(start),
Err(ReadError::ChainTooLong { .. })
));
let mut cycled = bytes.clone();
let dir_start = {
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let node = r.lookup(b"/EFI").expect("lookup");
match node.storage {
Storage::Chain(start) => start,
_ => panic!("a FAT16 subdirectory owns a chain"),
}
};
for copy in 0..layout.fats {
let off = at(&layout, layout.fat_start_sector(copy).expect("a table"))
+ table::entry_offset(FatType::Fat16, dir_start) as usize;
cycled[off..off + 2].copy_from_slice(&(dir_start as u16).to_le_bytes());
}
let reads = std::rc::Rc::new(std::cell::Cell::new(0usize));
struct Counting {
inner: Cursor<Vec<u8>>,
reads: std::rc::Rc<std::cell::Cell<usize>>,
}
impl std::io::Read for Counting {
fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
self.reads.set(self.reads.get() + 1);
std::io::Read::read(&mut self.inner, buf)
}
}
impl Seek for Counting {
fn seek(&mut self, pos: SeekFrom) -> std::io::Result<u64> {
Seek::seek(&mut self.inner, pos)
}
}
let mut counted = Reader::open_with(
Counting {
inner: Cursor::new(cycled),
reads: std::rc::Rc::clone(&reads),
},
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let dir = counted.lookup(b"/EFI").expect("lookup");
let before = reads.get();
assert!(
matches!(counted.read_dir(&dir), Err(ReadError::ChainTooLong { .. })),
"a directory whose chain cycles is refused"
);
assert!(
reads.get() - before < 64,
"a directory cycling on one cluster cost {} reads",
reads.get() - before
);
assert!(!r.scan().is_clean());
}
#[test]
fn a_chain_looping_onto_itself_is_told_apart_from_a_cluster_two_chains_share() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let mut bytes = image.into_bytes();
let start = {
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let node = r.lookup(b"/a-long-file-name.text").expect("lookup");
match node.storage {
Storage::Chain(start) => start,
_ => panic!("the fixture's multi-cluster file owns no chain"),
}
};
for copy in 0..layout.fats {
let off = at(&layout, layout.fat_start_sector(copy).expect("a table"))
+ table::entry_offset(FatType::Fat16, start + 1) as usize;
bytes[off..off + 2].copy_from_slice(&(start as u16).to_le_bytes());
}
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let report = r.scan();
let said = report
.anomalies()
.iter()
.find(|a| a.detail.contains("loops"))
.unwrap_or_else(|| panic!("no loop finding: {}", report.to_report().to_table()))
.detail
.clone();
assert!(
said.contains(&format!(
"the chain from cluster {start} returns to cluster {start}"
)),
"{said}"
);
assert!(
said.contains("a-long-file-name.text"),
"the owning path rides along: {said}"
);
assert!(
!report
.anomalies()
.iter()
.any(|a| a.detail.contains("another chain")),
"a loop is not a cross-link: {}",
report.to_report().to_table()
);
}
#[test]
fn the_reader_never_panics_on_mangled_images() {
let image = image(2, FatTypeRequest::Exactly(FatType::Fat12)).into_bytes();
fn drive(bytes: &[u8]) {
for options in [
OpenOptions::new(),
OpenOptions::new().policy(ReadPolicy::Lenient),
OpenOptions::new()
.policy(ReadPolicy::Lenient)
.charset(ShortNameCharset::Cp437),
OpenOptions::new().base(512).policy(ReadPolicy::Lenient),
] {
let Ok(mut r) = Reader::open_with(Cursor::new(bytes), &options) else {
continue;
};
let _ = r.verify_tables();
let _ = r.info_sector();
let _ = r.volume_label();
let _ = r.scan();
if let Ok(entries) = r.walk() {
for e in &entries {
let _ = r.read_data(&e.node);
if let Storage::Chain(start) = e.node.storage {
let _ = r.chain(start);
}
}
for e in &entries {
let _ = r.lookup(&e.path);
}
}
for path in [&b"/"[..], b"/../..", b"/a/b/c", b"//./"] {
let _ = r.lookup(path);
}
}
}
drive(&image);
for (off, len, fill) in [
(11usize, 2usize, 0xffu8), (13, 1, 0x00), (14, 2, 0xff), (16, 1, 0xff), (17, 2, 0xff), (19, 2, 0xff), (22, 2, 0xff), (32, 4, 0xff), ] {
let mut mangled = image.clone();
mangled[off..off + len].fill(fill);
drive(&mangled);
}
for len in [0usize, 1, 511, 512, 513, 1024, 4096, 65_536] {
drive(&image[..len.min(image.len())]);
}
let mut flip = image.clone();
let span = flip.len().min(96 * 1024);
let mut i = 0usize;
while i < span {
let orig = flip[i];
flip[i] ^= 0xff;
drive(&flip);
flip[i] = orig;
i += 251; }
drive(&vec![0x00u8; 8192]);
drive(&vec![0xffu8; 8192]);
let ramp: Vec<u8> = (0..8192u32).map(|k| (k % 256) as u8).collect();
drive(&ramp);
}
}