#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
pub mod decmpfs;
#[cfg(feature = "vfs")]
pub mod vfs;
pub const VOLUME_HEADER_OFFSET: usize = 1024;
pub(crate) const SIG_HFS_PLUS: u16 = 0x482B;
pub(crate) const SIG_HFSX: u16 = 0x4858;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HfsKind {
HfsPlus,
Hfsx,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct HfsVolume {
pub kind: HfsKind,
pub version: u16,
pub file_count: u32,
pub folder_count: u32,
pub block_size: u32,
pub total_blocks: u32,
pub free_blocks: u32,
}
impl HfsVolume {
#[must_use]
pub fn volume_size(&self) -> u64 {
u64::from(self.block_size) * u64::from(self.total_blocks)
}
}
#[must_use]
pub fn parse(volume: &[u8]) -> Option<HfsVolume> {
let h = VOLUME_HEADER_OFFSET;
if volume.len() < h + 52 {
return None;
}
let hdr = &volume[h..];
let kind = match be16(&hdr[0..2]) {
SIG_HFS_PLUS => HfsKind::HfsPlus,
SIG_HFSX => HfsKind::Hfsx,
_ => return None,
};
Some(HfsVolume {
kind,
version: be16(&hdr[2..4]),
file_count: be32(&hdr[32..36]),
folder_count: be32(&hdr[36..40]),
block_size: be32(&hdr[40..44]),
total_blocks: be32(&hdr[44..48]),
free_blocks: be32(&hdr[48..52]),
})
}
const ROOT_FOLDER_CNID: u32 = 2;
const RECORD_FOLDER: i16 = 1;
const RECORD_FILE: i16 = 2;
pub const MAX_LEAF_NODES: u32 = 65536;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HfsEntry {
pub name: String,
pub is_dir: bool,
pub cnid: u32,
}
pub struct CatalogLoc {
pub cat_base: usize,
pub node_size: usize,
pub first_leaf: u32,
pub block_size: usize,
}
pub(crate) const EXTENTS_FORK_OFFSET: usize = 192;
pub(crate) const CATALOG_FORK_OFFSET: usize = 272;
pub(crate) const ATTRIBUTES_FORK_OFFSET: usize = 352;
pub fn locate_catalog(volume: &[u8]) -> Option<CatalogLoc> {
locate_btree(volume, CATALOG_FORK_OFFSET)
}
pub(crate) fn locate_attributes(volume: &[u8]) -> Option<CatalogLoc> {
locate_btree(volume, ATTRIBUTES_FORK_OFFSET)
}
pub fn locate_extents(volume: &[u8]) -> Option<CatalogLoc> {
locate_btree(volume, EXTENTS_FORK_OFFSET)
}
pub(crate) fn locate_btree(volume: &[u8], fork_offset_in_header: usize) -> Option<CatalogLoc> {
let h = VOLUME_HEADER_OFFSET;
let fork = h.checked_add(fork_offset_in_header)?;
if volume.len() < fork + 20 {
return None;
}
match be16(&volume[h..h + 2]) {
SIG_HFS_PLUS | SIG_HFSX => {}
_ => return None,
}
let block_size = be32(&volume[h + 40..h + 44]) as usize;
if block_size == 0 {
return None;
}
if be32(&volume[fork + 12..fork + 16]) == 0 {
return None;
}
let start_block = be32(&volume[fork + 16..fork + 20]) as usize;
let cat_base = start_block.checked_mul(block_size)?;
let hdr = cat_base.checked_add(14)?;
if volume.len() < hdr + 20 {
return None;
}
let first_leaf = be32(&volume[hdr + 10..hdr + 14]);
let node_size = be16(&volume[hdr + 18..hdr + 20]) as usize;
if node_size < 14 {
return None;
}
Some(CatalogLoc {
cat_base,
node_size,
first_leaf,
block_size,
})
}
pub fn for_each_record(volume: &[u8], loc: &CatalogLoc, mut f: impl FnMut(&[u8])) {
let _ = walk_leaves(volume, loc, false, |rec| {
f(rec);
Ok(())
});
}
fn walk_leaves(
volume: &[u8],
loc: &CatalogLoc,
strict: bool,
mut f: impl FnMut(&[u8]) -> Result<(), HfsXattrError>,
) -> Result<(), HfsXattrError> {
let mut node = loc.first_leaf;
let mut walked = 0u32;
while node != 0 {
if walked >= MAX_LEAF_NODES {
return Err(HfsXattrError::LeafChain {
node,
detail: format!(
"the fLink chain runs past {MAX_LEAF_NODES} leaf nodes, so it loops or is corrupt"
),
});
}
walked += 1;
let Some(nd) = (node as usize)
.checked_mul(loc.node_size)
.and_then(|x| x.checked_add(loc.cat_base))
.and_then(|off| volume.get(off..off.checked_add(loc.node_size)?))
else {
return Err(HfsXattrError::LeafChain {
node,
detail: format!(
"node {node} ({}-byte nodes from byte {}) lies outside the {}-byte volume",
loc.node_size,
loc.cat_base,
volume.len()
),
});
};
let f_link = be32(&nd[0..4]);
let num_records = be16(&nd[10..12]) as usize;
for i in 0..num_records {
let Some(slot) = loc.node_size.checked_sub(2 * (i + 1)) else {
if strict {
return Err(HfsXattrError::LeafChain {
node,
detail: format!(
"node {node} declares {num_records} records, more offsets than a {}-byte node holds",
loc.node_size
),
});
}
break;
};
let rec = be16(&nd[slot..slot + 2]) as usize;
if rec + 8 <= loc.node_size {
f(&nd[rec..])?;
} else if strict {
return Err(HfsXattrError::LeafChain {
node,
detail: format!(
"record {i} of node {node} starts at byte {rec}, past the {}-byte node",
loc.node_size
),
});
}
}
node = f_link;
}
Ok(())
}
#[must_use]
pub fn list_root(volume: &[u8]) -> Option<Vec<HfsEntry>> {
list_dir(volume, ROOT_FOLDER_CNID)
}
#[must_use]
pub fn list_dir(volume: &[u8], parent_cnid: u32) -> Option<Vec<HfsEntry>> {
let loc = locate_catalog(volume)?;
let mut entries = Vec::new();
for_each_record(volume, &loc, |rec| {
if let Some((parent, entry)) = record_entry(rec) {
if parent == parent_cnid {
entries.push(entry);
}
}
});
Some(entries)
}
#[must_use]
pub fn read_file(volume: &[u8], cnid: u32) -> Option<Vec<u8>> {
let loc = locate_catalog(volume)?;
let mut forks: Option<(Fork, Fork)> = None;
for_each_record(volume, &loc, |rec| {
if forks.is_none() {
forks = file_forks(rec, cnid);
}
});
let (data_fork, resource_fork) = forks?;
if let Some(xattr) = decmpfs_xattr(volume, cnid) {
let resource = if resource_fork.logical > 0 {
fork_bytes(volume, loc.block_size, &resource_fork)
} else {
None
};
return decmpfs::decompress(&xattr, resource.as_deref()).ok();
}
fork_bytes(volume, loc.block_size, &data_fork)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct HfsStat {
pub cnid: u32,
pub is_dir: bool,
pub size: u64,
pub created: u32,
pub modified: u32,
pub accessed: u32,
}
#[must_use]
pub fn stat(volume: &[u8], cnid: u32) -> Option<HfsStat> {
let loc = locate_catalog(volume)?;
let mut found = None;
for_each_record(volume, &loc, |rec| {
if found.is_none() {
found = record_stat(rec, cnid);
}
});
found
}
fn record_stat(rec: &[u8], cnid: u32) -> Option<HfsStat> {
if rec.len() < 8 {
return None;
}
let key_len = be16(&rec[0..2]) as usize;
let data = 2 + key_len;
if data + 32 > rec.len() {
return None;
}
let is_dir = match i16::from_be_bytes([rec[data], rec[data + 1]]) {
RECORD_FOLDER => true,
RECORD_FILE => false,
_ => return None, };
if be32(&rec[data + 8..data + 12]) != cnid {
return None;
}
let created = be32(&rec[data + 16..data + 20]);
let modified = be32(&rec[data + 20..data + 24]);
let accessed = be32(&rec[data + 28..data + 32]);
let size = if is_dir {
0
} else if data + 96 <= rec.len() {
u64::from_be_bytes(rec[data + 88..data + 96].try_into().ok()?)
} else {
0
};
Some(HfsStat {
cnid,
is_dir,
size,
created,
modified,
accessed,
})
}
fn record_entry(rec: &[u8]) -> Option<(u32, HfsEntry)> {
if rec.len() < 8 {
return None;
}
let key_len = be16(&rec[0..2]) as usize;
let parent_id = be32(&rec[2..6]);
let name_len = be16(&rec[6..8]) as usize;
let name_end = 8 + name_len * 2;
if name_end > rec.len() {
return None;
}
let name = decode_utf16(&rec[8..name_end]);
let data = 2 + key_len;
if data + 12 > rec.len() {
return None;
}
let is_dir = match i16::from_be_bytes([rec[data], rec[data + 1]]) {
RECORD_FOLDER => true,
RECORD_FILE => false,
_ => return None, };
let cnid = be32(&rec[data + 8..data + 12]);
Some((parent_id, HfsEntry { name, is_dir, cnid }))
}
struct Fork {
logical: u64,
extents: Vec<(u32, u32)>,
}
const DECMPFS_XATTR_NAME: &str = "com.apple.decmpfs";
const ATTR_INLINE_DATA: u32 = 0x10;
fn file_forks(rec: &[u8], cnid: u32) -> Option<(Fork, Fork)> {
if rec.len() < 8 {
return None;
}
let key_len = be16(&rec[0..2]) as usize;
let data = 2 + key_len;
if data + 168 > rec.len() {
return None;
}
if i16::from_be_bytes([rec[data], rec[data + 1]]) != RECORD_FILE {
return None;
}
if be32(&rec[data + 8..data + 12]) != cnid {
return None;
}
let data_fork = parse_fork(&rec[data + 88..])?;
let resource_fork = if data + 248 <= rec.len() {
parse_fork(&rec[data + 168..])?
} else {
Fork {
logical: 0,
extents: Vec::new(),
}
};
Some((data_fork, resource_fork))
}
fn parse_fork(fork: &[u8]) -> Option<Fork> {
if fork.len() < 80 {
return None;
}
let logical = u64::from_be_bytes(fork[0..8].try_into().ok()?);
let mut extents = Vec::new();
for i in 0..8 {
let e = 16 + i * 8;
let start = be32(&fork[e..e + 4]);
let count = be32(&fork[e + 4..e + 8]);
if count != 0 {
extents.push((start, count));
}
}
Some(Fork { logical, extents })
}
fn fork_bytes(volume: &[u8], block_size: usize, fork: &Fork) -> Option<Vec<u8>> {
let logical = fork.logical as usize;
let mut data = Vec::with_capacity(logical.min(1 << 20));
for &(start, count) in &fork.extents {
if data.len() >= logical {
break;
}
let begin = (start as usize).checked_mul(block_size)?;
let len = (count as usize).checked_mul(block_size)?;
let end = begin.checked_add(len)?.min(volume.len());
if begin >= volume.len() {
break;
}
data.extend_from_slice(&volume[begin..end]);
}
data.truncate(logical);
Some(data)
}
pub fn decmpfs_xattr(volume: &[u8], cnid: u32) -> Option<Vec<u8>> {
let loc = locate_attributes(volume)?;
let mut found = None;
for_each_record(volume, &loc, |rec| {
if found.is_none() {
found = attr_inline_value(rec, cnid, DECMPFS_XATTR_NAME);
}
});
found
}
fn attr_inline_value(rec: &[u8], cnid: u32, want_name: &str) -> Option<Vec<u8>> {
if rec.len() < 14 {
return None;
}
let key_len = be16(&rec[0..2]) as usize;
if be32(&rec[4..8]) != cnid {
return None;
}
let name_len = be16(&rec[12..14]) as usize;
let name_end = 14usize.checked_add(name_len.checked_mul(2)?)?;
if name_end > rec.len() {
return None;
}
if decode_utf16(&rec[14..name_end]) != want_name {
return None;
}
let body = 2 + key_len;
if body + 16 > rec.len() {
return None;
}
if be32(&rec[body..body + 4]) != ATTR_INLINE_DATA {
return None;
}
let attr_size = be32(&rec[body + 12..body + 16]) as usize;
let end = body.checked_add(16)?.checked_add(attr_size)?;
if end > rec.len() {
return None;
}
Some(rec[body + 16..end].to_vec())
}
const ATTR_FORK_DATA: u32 = 0x20;
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HfsXattrValue {
Inline(Vec<u8>),
Fork {
logical: u64,
},
}
impl HfsXattrValue {
#[must_use]
pub fn len(&self) -> u64 {
match self {
Self::Inline(b) => b.len() as u64,
Self::Fork { logical } => *logical,
}
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.len() == 0
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HfsXattr {
pub name: String,
pub value: HfsXattrValue,
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum HfsXattrError {
AttributesBtree {
detail: String,
},
LeafChain {
node: u32,
detail: String,
},
Record {
name: Option<String>,
detail: String,
bytes: Vec<u8>,
},
}
impl std::fmt::Display for HfsXattrError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::AttributesBtree { detail } => write!(f, "attributes B-tree unreadable: {detail}"),
Self::LeafChain { node, detail } => {
write!(
f,
"attributes B-tree leaf chain broken at node {node}: {detail}"
)
}
Self::Record {
name,
detail,
bytes,
} => {
let hex = bytes.iter().fold(String::new(), |mut s, b| {
let _ = std::fmt::Write::write_fmt(&mut s, format_args!("{b:02x}"));
s
});
match name {
Some(n) => write!(f, "attribute {n}: {detail} (record starts {hex})"),
None => write!(f, "attribute record: {detail} (record starts {hex})"),
}
}
}
}
}
impl std::error::Error for HfsXattrError {}
fn record_prefix(rec: &[u8]) -> Vec<u8> {
rec[..rec.len().min(32)].to_vec()
}
fn attributes_btree(volume: &[u8]) -> Result<Option<CatalogLoc>, HfsXattrError> {
let fork = VOLUME_HEADER_OFFSET + ATTRIBUTES_FORK_OFFSET;
let Some(total_blocks) = volume.get(fork + 12..fork + 16) else {
return Err(HfsXattrError::AttributesBtree {
detail: format!(
"the {}-byte volume ends before the attributes fork record at byte {fork}",
volume.len()
),
});
};
if be32(total_blocks) == 0 {
return Ok(None);
}
locate_attributes(volume)
.map(Some)
.ok_or_else(|| HfsXattrError::AttributesBtree {
detail: format!(
"the volume header declares {} attributes-file blocks, but the B-tree header is unusable (bad signature, block size, location or node size)",
be32(total_blocks)
),
})
}
pub fn list_xattrs(volume: &[u8], cnid: u32) -> Result<Vec<HfsXattr>, HfsXattrError> {
let Some(loc) = attributes_btree(volume)? else {
return Ok(Vec::new());
};
let mut out = Vec::new();
walk_leaves(volume, &loc, true, |rec| {
if let Some(x) = parse_attr_record(rec, cnid)? {
out.push(x);
}
Ok(())
})?;
Ok(out)
}
pub fn read_xattr(volume: &[u8], cnid: u32, name: &str) -> Result<Option<Vec<u8>>, HfsXattrError> {
let Some(loc) = attributes_btree(volume)? else {
return Ok(None);
};
let block_size = loc.block_size;
let mut found = None;
walk_leaves(volume, &loc, true, |rec| {
if found.is_some() {
return Ok(());
}
let Some(key) = attr_key(rec, cnid)? else {
return Ok(());
};
if key.name != name || key.start_block != 0 {
return Ok(());
}
let body = key.body;
found = Some(match be32(&rec[body..body + 4]) {
ATTR_INLINE_DATA => inline_value(rec, &key)?,
ATTR_FORK_DATA => {
let fork = fork_record(rec, &key)?;
let bytes = fork_bytes(volume, block_size, &fork).unwrap_or_default();
if (bytes.len() as u64) < fork.logical {
return Err(HfsXattrError::Record {
name: Some(key.name),
detail: format!(
"its extents yield {} of its {} bytes; the rest is in kHFSPlusAttrExtents records or past the volume end, and this reader does not assemble it",
bytes.len(),
fork.logical
),
bytes: record_prefix(rec),
});
}
bytes
}
other => return Err(unknown_record_type(rec, key, other)),
});
Ok(())
})?;
Ok(found)
}
struct AttrKey {
name: String,
body: usize,
start_block: u32,
}
fn attr_key(rec: &[u8], cnid: u32) -> Result<Option<AttrKey>, HfsXattrError> {
let damaged = |name: Option<String>, detail: String| HfsXattrError::Record {
name,
detail,
bytes: record_prefix(rec),
};
if rec.len() < 14 {
return Err(damaged(
None,
format!(
"a {}-byte record is too short for its 14-byte key header",
rec.len()
),
));
}
let key_len = be16(&rec[0..2]) as usize;
if be32(&rec[4..8]) != cnid {
return Ok(None);
}
let start_block = be32(&rec[8..12]);
let name_len = be16(&rec[12..14]) as usize;
let name_end = 14 + name_len * 2;
let Some(name_bytes) = rec.get(14..name_end) else {
return Err(damaged(
None,
format!(
"its {name_len}-character name runs past the {}-byte record",
rec.len()
),
));
};
let name = decode_utf16(name_bytes);
let body = 2 + key_len;
if body + 4 > rec.len() {
return Err(damaged(
Some(name),
format!(
"keyLength {key_len} puts the record body past the {}-byte record",
rec.len()
),
));
}
Ok(Some(AttrKey {
name,
body,
start_block,
}))
}
fn inline_value(rec: &[u8], key: &AttrKey) -> Result<Vec<u8>, HfsXattrError> {
let body = key.body;
let size = rec.get(body + 12..body + 16).map(|b| be32(b) as usize);
match size.and_then(|n| rec.get(body + 16..body + 16 + n)) {
Some(v) => Ok(v.to_vec()),
None => Err(HfsXattrError::Record {
name: Some(key.name.clone()),
detail: match size {
Some(n) => format!(
"its inline attrSize {n} runs past the {}-byte record",
rec.len()
),
None => format!(
"the {}-byte record ends inside its inline-data header",
rec.len()
),
},
bytes: record_prefix(rec),
}),
}
}
fn fork_record(rec: &[u8], key: &AttrKey) -> Result<Fork, HfsXattrError> {
rec.get(key.body + 8..)
.and_then(parse_fork)
.ok_or_else(|| HfsXattrError::Record {
name: Some(key.name.clone()),
detail: format!(
"the {}-byte record ends inside its 80-byte fork data",
rec.len()
),
bytes: record_prefix(rec),
})
}
fn unknown_record_type(rec: &[u8], key: AttrKey, record_type: u32) -> HfsXattrError {
HfsXattrError::Record {
name: Some(key.name),
detail: format!("record type 0x{record_type:08x} is not one this reader decodes"),
bytes: record_prefix(rec),
}
}
fn parse_attr_record(rec: &[u8], cnid: u32) -> Result<Option<HfsXattr>, HfsXattrError> {
let Some(key) = attr_key(rec, cnid)? else {
return Ok(None);
};
if key.start_block != 0 {
return Ok(None);
}
let body = key.body;
let value = match be32(&rec[body..body + 4]) {
ATTR_INLINE_DATA => HfsXattrValue::Inline(inline_value(rec, &key)?),
ATTR_FORK_DATA => HfsXattrValue::Fork {
logical: fork_record(rec, &key)?.logical,
},
other => return Err(unknown_record_type(rec, key, other)),
};
Ok(Some(HfsXattr {
name: key.name,
value,
}))
}
pub fn decode_utf16(bytes: &[u8]) -> String {
let units: Vec<u16> = bytes
.chunks_exact(2)
.map(|c| u16::from_be_bytes([c[0], c[1]]))
.collect();
String::from_utf16_lossy(&units)
}
pub fn be16(b: &[u8]) -> u16 {
u16::from_be_bytes([b[0], b[1]])
}
pub fn be32(b: &[u8]) -> u32 {
u32::from_be_bytes([b[0], b[1], b[2], b[3]])
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HfsPathEntry {
pub path: String,
pub is_dir: bool,
pub cnid: u32,
}
#[must_use]
pub fn walk(volume: &[u8]) -> Option<Vec<HfsPathEntry>> {
list_dir(volume, ROOT_FOLDER_CNID)?;
let mut out = Vec::new();
let mut visited = std::collections::HashSet::new();
visited.insert(ROOT_FOLDER_CNID);
let mut stack = vec![(ROOT_FOLDER_CNID, String::new())];
while let Some((parent, prefix)) = stack.pop() {
let Some(entries) = list_dir(volume, parent) else {
continue;
};
for e in entries {
let path = if prefix.is_empty() {
e.name.clone()
} else {
format!("{prefix}/{}", e.name)
};
if e.is_dir && visited.insert(e.cnid) {
stack.push((e.cnid, path.clone()));
}
out.push(HfsPathEntry {
path,
is_dir: e.is_dir,
cnid: e.cnid,
});
}
}
Some(out)
}
#[cfg(test)]
mod xattr_record_tests {
use super::{parse_attr_record, walk_leaves, CatalogLoc, HfsXattrError};
fn key_then(record_type: u32, total_len: usize) -> Vec<u8> {
let mut r = vec![0u8; total_len];
r[0..2].copy_from_slice(&14u16.to_be_bytes());
r[4..8].copy_from_slice(&7u32.to_be_bytes());
r[12..14].copy_from_slice(&1u16.to_be_bytes());
r[14..16].copy_from_slice(&u16::from(b'a').to_be_bytes());
r[16..20].copy_from_slice(&record_type.to_be_bytes());
r
}
#[test]
fn an_inline_record_ending_inside_its_header_is_an_error() {
let err = parse_attr_record(&key_then(0x10, 20), 7).unwrap_err();
assert!(
err.to_string()
.contains("ends inside its inline-data header"),
"{err}"
);
}
#[test]
fn a_fork_record_ending_inside_its_fork_data_is_an_error() {
let err = parse_attr_record(&key_then(0x20, 40), 7).unwrap_err();
assert!(err.to_string().contains("80-byte fork data"), "{err}");
}
#[test]
fn a_continuation_record_is_not_listed_as_its_own_attribute() {
let mut r = key_then(0x30, 40);
r[8..12].copy_from_slice(&5u32.to_be_bytes());
assert_eq!(parse_attr_record(&r, 7), Ok(None));
}
#[test]
fn an_attribute_with_an_empty_value_is_listed_and_reports_empty() {
let mut r = key_then(0x10, 40); r[28..32].copy_from_slice(&0u32.to_be_bytes());
let x = parse_attr_record(&r, 7).unwrap().unwrap();
assert_eq!(x.name, "a");
assert!(x.value.is_empty());
assert!(!super::HfsXattrValue::Fork { logical: 1 }.is_empty());
}
#[test]
fn a_record_of_another_file_is_not_this_files_business() {
assert_eq!(parse_attr_record(&key_then(0x99, 20), 8), Ok(None));
}
#[test]
fn a_strict_walk_reports_a_record_count_the_node_cannot_hold() {
let mut vol = vec![0u8; 128];
vol[64 + 10..64 + 12].copy_from_slice(&40u16.to_be_bytes());
let loc = CatalogLoc {
cat_base: 0,
node_size: 64,
first_leaf: 1,
block_size: 512,
};
let err = walk_leaves(&vol, &loc, true, |_| Ok(())).unwrap_err();
assert!(
matches!(&err, HfsXattrError::LeafChain { node: 1, detail } if detail.contains("declares 40 records")),
"{err:?}"
);
let mut seen = 0;
super::for_each_record(&vol, &loc, |_| seen += 1);
assert_eq!(seen, 32, "every slot that fits is still visited");
}
}