use crate::bytes::{get_u16, get_u32, get_u64, put_u16, put_u32, put_u64};
use super::ParseError;
pub mod record_kind {
pub const SNAPSHOT_META: u8 = 1;
pub const PHYSICAL_EXTENT: u8 = 2;
pub const INODE: u8 = 3;
pub const XATTR: u8 = 4;
pub const SIBLING_LINK: u8 = 5;
pub const DATA_STREAM_ID: u8 = 6;
pub const CRYPTO_STATE: u8 = 7;
pub const FILE_EXTENT: u8 = 8;
pub const DIR_ENTRY: u8 = 9;
pub const DIR_STATS: u8 = 10;
pub const SNAPSHOT_NAME: u8 = 11;
pub const SIBLING_MAP: u8 = 12;
pub const FILE_INFO: u8 = 13;
}
pub const ID_MASK: u64 = 0x0FFF_FFFF_FFFF_FFFF;
pub const KIND_SHIFT: u32 = 60;
pub mod inode_number {
pub const ROOT_PARENT: u64 = 1;
pub const ROOT: u64 = 2;
pub const PRIVATE: u64 = 3;
pub const FIRST_USER: u64 = 16;
}
pub const BSD_COMPRESSED: u32 = 0x20;
pub const INTERNAL_EVER_CLONED: u64 = 0x400;
pub const INTERNAL_WITHOUT_RESOURCE_FORK: u64 = 0x8000;
pub const INTERNAL_WITH_RESOURCE_FORK: u64 = 0x4000;
pub const INTERNAL_WITH_SECURITY_ATTRIBUTE: u64 = 0x40;
pub const INTERNAL_COMPRESSED: u64 = 0x40000;
pub const INTERNAL_BEING_TRUNCATED: u64 = 0x80;
pub const SYMLINK_XATTR: &[u8] = b"com.apple.fs.symlink";
pub const DECMPFS_XATTR: &[u8] = b"com.apple.decmpfs";
pub const RESOURCE_FORK_XATTR: &[u8] = b"com.apple.ResourceFork";
pub const SECURITY_XATTR: &[u8] = b"com.apple.system.Security";
pub mod inode_field {
pub const NAME: u8 = 4;
pub const PREV_FSIZE: u8 = 5;
pub const DATA_STREAM: u8 = 8;
pub const SPARSE_BYTES: u8 = 13;
pub const DEVICE: u8 = 14;
}
pub const SIBLING_ID_FIELD: u8 = 1;
pub mod xattr_flags {
pub const STREAM: u16 = 0x1;
pub const EMBEDDED: u16 = 0x2;
pub const FILESYSTEM_OWNED: u16 = 0x4;
pub const SET_THROUGH_SETXATTR: u16 = 0x10;
}
pub const ENTRY_TYPE_MASK: u16 = 0x000F;
pub const EXTENT_LENGTH_MASK: u64 = 0x00FF_FFFF_FFFF_FFFF;
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
pub struct KeyHeader {
pub id: u64,
pub kind: u8,
}
impl KeyHeader {
pub const SIZE: usize = 8;
pub fn read_from(key: &[u8]) -> Result<Self, ParseError> {
ParseError::need("record key", Self::SIZE, key)?;
let word = get_u64(key, 0);
Ok(Self {
id: word & ID_MASK,
kind: (word >> KIND_SHIFT) as u8,
})
}
#[must_use]
pub const fn word(&self) -> u64 {
(self.id & ID_MASK) | ((self.kind as u64) << KIND_SHIFT)
}
pub fn write_to(&self, buf: &mut [u8]) {
assert!(buf.len() >= Self::SIZE, "a record key needs 8 bytes");
put_u64(buf, 0, self.word());
}
#[must_use]
pub fn key(&self, tail: &[u8]) -> Vec<u8> {
let mut key = Vec::with_capacity(Self::SIZE + tail.len());
key.extend_from_slice(&self.word().to_le_bytes());
key.extend_from_slice(tail);
key
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct ExtendedField<'a> {
pub kind: u8,
pub flags: u8,
pub data: &'a [u8],
}
pub fn extended_fields(blob: &[u8]) -> Result<Vec<ExtendedField<'_>>, ParseError> {
if blob.is_empty() {
return Ok(Vec::new());
}
ParseError::need("extended fields", 4, blob)?;
let count = usize::from(get_u16(blob, 0));
let descriptors_end = 4 + 4 * count;
ParseError::need("extended field descriptors", descriptors_end, blob)?;
let mut fields = Vec::with_capacity(count);
let mut at = descriptors_end;
for i in 0..count {
let d = 4 + 4 * i;
let size = usize::from(get_u16(blob, d + 2));
let end = at + size;
ParseError::need("extended field data", end, blob)?;
fields.push(ExtendedField {
kind: blob[d],
flags: blob[d + 1],
data: &blob[at..end],
});
at += size.next_multiple_of(8);
}
Ok(fields)
}
#[must_use]
pub fn extended_field_blob(fields: &[ExtendedField<'_>]) -> Vec<u8> {
if fields.is_empty() {
return Vec::new();
}
let narrow = |n: usize| u16::try_from(n).expect("an extended-field count or size fits 16 bits");
let descriptors_end = 4 + 4 * fields.len();
let mut out = vec![0u8; descriptors_end];
put_u16(&mut out, 0, narrow(fields.len()));
for (i, f) in fields.iter().enumerate() {
let d = 4 + 4 * i;
out[d] = f.kind;
out[d + 1] = f.flags;
put_u16(&mut out, d + 2, narrow(f.data.len()));
}
for f in fields {
out.extend_from_slice(f.data);
out.resize(
out.len() + f.data.len().next_multiple_of(8) - f.data.len(),
0,
);
}
let used = narrow(out.len() - descriptors_end);
put_u16(&mut out, 2, used);
out
}
#[must_use]
pub fn field<'a>(fields: &[ExtendedField<'a>], kind: u8) -> Option<&'a [u8]> {
fields.iter().find(|f| f.kind == kind).map(|f| f.data)
}
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub struct DataStream {
pub size: u64,
pub allocated: u64,
pub crypto_id: u64,
pub bytes_written: u64,
pub bytes_read: u64,
}
impl DataStream {
pub const SIZE: usize = 40;
pub fn read_from(buf: &[u8]) -> Result<Self, ParseError> {
ParseError::need("data stream", Self::SIZE, buf)?;
Ok(Self {
size: get_u64(buf, 0),
allocated: get_u64(buf, 8),
crypto_id: get_u64(buf, 16),
bytes_written: get_u64(buf, 24),
bytes_read: get_u64(buf, 32),
})
}
pub fn write_to(&self, buf: &mut [u8]) {
assert!(buf.len() >= Self::SIZE, "a data stream needs 40 bytes");
put_u64(buf, 0, self.size);
put_u64(buf, 8, self.allocated);
put_u64(buf, 16, self.crypto_id);
put_u64(buf, 24, self.bytes_written);
put_u64(buf, 32, self.bytes_read);
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
pub struct InodeValue {
pub parent_id: u64,
pub private_id: u64,
pub create_time: i64,
pub modify_time: i64,
pub change_time: i64,
pub access_time: i64,
pub internal_flags: u64,
pub links_or_children: i32,
pub protection_class: u32,
pub write_generation: u32,
pub bsd_flags: u32,
pub owner: u32,
pub group: u32,
pub mode: u16,
pub pad: u16,
pub uncompressed_size: u64,
}
impl InodeValue {
pub const SIZE: usize = 92;
pub fn read_from(value: &[u8]) -> Result<Self, ParseError> {
ParseError::need("inode", Self::SIZE, value)?;
Ok(Self {
parent_id: get_u64(value, 0),
private_id: get_u64(value, 8),
create_time: get_u64(value, 16) as i64,
modify_time: get_u64(value, 24) as i64,
change_time: get_u64(value, 32) as i64,
access_time: get_u64(value, 40) as i64,
internal_flags: get_u64(value, 48),
links_or_children: get_u32(value, 56) as i32,
protection_class: get_u32(value, 60),
write_generation: get_u32(value, 64),
bsd_flags: get_u32(value, 68),
owner: get_u32(value, 72),
group: get_u32(value, 76),
mode: get_u16(value, 80),
pad: get_u16(value, 82),
uncompressed_size: get_u64(value, 84),
})
}
pub fn write_to(&self, buf: &mut [u8]) {
assert!(buf.len() >= Self::SIZE, "an inode needs 92 bytes");
put_u64(buf, 0, self.parent_id);
put_u64(buf, 8, self.private_id);
put_u64(buf, 16, self.create_time as u64);
put_u64(buf, 24, self.modify_time as u64);
put_u64(buf, 32, self.change_time as u64);
put_u64(buf, 40, self.access_time as u64);
put_u64(buf, 48, self.internal_flags);
put_u32(buf, 56, self.links_or_children as u32);
put_u32(buf, 60, self.protection_class);
put_u32(buf, 64, self.write_generation);
put_u32(buf, 68, self.bsd_flags);
put_u32(buf, 72, self.owner);
put_u32(buf, 76, self.group);
put_u16(buf, 80, self.mode);
put_u16(buf, 82, self.pad);
put_u64(buf, 84, self.uncompressed_size);
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct EntryKey<'a> {
pub hash: u32,
pub name: &'a [u8],
}
impl<'a> EntryKey<'a> {
pub fn read_from(key: &'a [u8]) -> Result<Self, ParseError> {
ParseError::need("directory entry key", 12, key)?;
let word = get_u32(key, 8);
let len = (word & 0x3FF) as usize;
let end = 12 + len;
ParseError::need("directory entry name", end, key)?;
let stored = &key[12..end];
let Some((&0, name)) = stored.split_last() else {
return Err(ParseError::Unterminated {
structure: "directory entry name",
});
};
Ok(Self {
hash: word >> 10,
name,
})
}
}
impl EntryKey<'_> {
#[must_use]
pub fn to_key(&self, parent: u64) -> Vec<u8> {
assert!(self.hash < 1 << 22, "a directory entry's hash is 22 bits");
let len = u32::try_from(self.name.len() + 1)
.ok()
.filter(|len| *len < 1 << 10)
.expect("a directory entry's name with its NUL fits 10 bits");
let mut key = vec![0u8; 12];
KeyHeader {
id: parent,
kind: record_kind::DIR_ENTRY,
}
.write_to(&mut key);
put_u32(&mut key, 8, (self.hash << 10) | len);
key.extend_from_slice(self.name);
key.push(0);
key
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
pub struct EntryValue {
pub file_id: u64,
pub date_added: i64,
pub flags: u16,
}
impl EntryValue {
pub const SIZE: usize = 18;
pub fn read_from(value: &[u8]) -> Result<Self, ParseError> {
ParseError::need("directory entry", Self::SIZE, value)?;
Ok(Self {
file_id: get_u64(value, 0),
date_added: get_u64(value, 8) as i64,
flags: get_u16(value, 16),
})
}
#[must_use]
pub const fn entry_type(&self) -> u8 {
(self.flags & ENTRY_TYPE_MASK) as u8
}
pub fn write_to(&self, buf: &mut [u8]) {
assert!(buf.len() >= Self::SIZE, "a directory entry needs 18 bytes");
put_u64(buf, 0, self.file_id);
put_u64(buf, 8, self.date_added as u64);
put_u16(buf, 16, self.flags);
}
}
pub fn xattr_name(key: &[u8]) -> Result<&[u8], ParseError> {
ParseError::need("attribute key", 10, key)?;
let end = 10 + usize::from(get_u16(key, 8));
ParseError::need("attribute name", end, key)?;
match key[10..end].split_last() {
Some((&0, name)) => Ok(name),
_ => Err(ParseError::Unterminated {
structure: "attribute name",
}),
}
}
#[must_use]
pub fn xattr_key(id: u64, name: &[u8]) -> Vec<u8> {
let len = u16::try_from(name.len() + 1).expect("an attribute's name with its NUL fits 16 bits");
let mut tail = Vec::with_capacity(xattr_key_size(name.len()) - KeyHeader::SIZE);
tail.extend_from_slice(&len.to_le_bytes());
tail.extend_from_slice(name);
tail.push(0);
KeyHeader {
id,
kind: record_kind::XATTR,
}
.key(&tail)
}
#[must_use]
pub const fn xattr_key_size(len: usize) -> usize {
KeyHeader::SIZE + 2 + len + 1
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct XattrValue<'a> {
pub flags: u16,
pub data: &'a [u8],
}
impl<'a> XattrValue<'a> {
pub const HEADER_SIZE: usize = 4;
pub const STREAM_SIZE: usize = 8 + DataStream::SIZE;
pub fn read_from(value: &'a [u8]) -> Result<Self, ParseError> {
ParseError::need("attribute", Self::HEADER_SIZE, value)?;
let end = Self::HEADER_SIZE + usize::from(get_u16(value, 2));
ParseError::need("attribute data", end, value)?;
Ok(Self {
flags: get_u16(value, 0),
data: &value[Self::HEADER_SIZE..end],
})
}
#[must_use]
pub fn to_value(&self) -> Vec<u8> {
let len = u16::try_from(self.data.len()).expect("an attribute's data fits 16 bits");
let mut value = Vec::with_capacity(Self::HEADER_SIZE + self.data.len());
value.extend_from_slice(&self.flags.to_le_bytes());
value.extend_from_slice(&len.to_le_bytes());
value.extend_from_slice(self.data);
value
}
pub fn stream(&self) -> Result<(u64, DataStream), ParseError> {
ParseError::need("attribute stream", Self::STREAM_SIZE, self.data)?;
Ok((
get_u64(self.data, 0),
DataStream::read_from(&self.data[8..])?,
))
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct FileExtent {
pub logical: u64,
pub length: u64,
pub flags: u8,
pub physical_block: u64,
pub crypto_id: u64,
}
impl FileExtent {
pub const VALUE_SIZE: usize = 24;
pub fn read_from(key: &[u8], value: &[u8]) -> Result<Self, ParseError> {
ParseError::need("file extent key", 16, key)?;
ParseError::need("file extent", Self::VALUE_SIZE, value)?;
let word = get_u64(value, 0);
Ok(Self {
logical: get_u64(key, 8),
length: word & EXTENT_LENGTH_MASK,
flags: (word >> 56) as u8,
physical_block: get_u64(value, 8),
crypto_id: get_u64(value, 16),
})
}
}
impl FileExtent {
#[must_use]
pub fn to_record(&self, stream: u64) -> (Vec<u8>, Vec<u8>) {
let key = KeyHeader {
id: stream,
kind: record_kind::FILE_EXTENT,
}
.key(&self.logical.to_le_bytes());
let mut value = vec![0u8; Self::VALUE_SIZE];
put_u64(
&mut value,
0,
(self.length & EXTENT_LENGTH_MASK) | (u64::from(self.flags) << 56),
);
put_u64(&mut value, 8, self.physical_block);
put_u64(&mut value, 16, self.crypto_id);
(key, value)
}
}
pub const PHYSICAL_LENGTH_MASK: u64 = 0x0FFF_FFFF_FFFF_FFFF;
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct PhysicalExtent {
pub start: u64,
pub blocks: u64,
pub kind: u8,
pub owner: u64,
pub references: i32,
}
impl PhysicalExtent {
pub const VALUE_SIZE: usize = 20;
pub fn read_from(key: &[u8], value: &[u8]) -> Result<Self, ParseError> {
let header = KeyHeader::read_from(key)?;
ParseError::need("physical extent", Self::VALUE_SIZE, value)?;
let word = get_u64(value, 0);
Ok(Self {
start: header.id,
blocks: word & PHYSICAL_LENGTH_MASK,
kind: (word >> 60) as u8,
owner: get_u64(value, 8),
references: get_u32(value, 16) as i32,
})
}
}
impl PhysicalExtent {
#[must_use]
pub fn to_record(&self) -> (Vec<u8>, Vec<u8>) {
let key = KeyHeader {
id: self.start,
kind: record_kind::PHYSICAL_EXTENT,
}
.key(&[]);
let mut value = vec![0u8; Self::VALUE_SIZE];
put_u64(
&mut value,
0,
(self.blocks & PHYSICAL_LENGTH_MASK) | (u64::from(self.kind) << 60),
);
put_u64(&mut value, 8, self.owner);
put_u32(&mut value, 16, self.references as u32);
(key, value)
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct SiblingLink<'a> {
pub sibling_id: u64,
pub parent_id: u64,
pub name: &'a [u8],
}
impl<'a> SiblingLink<'a> {
pub fn read_from(key: &[u8], value: &'a [u8]) -> Result<Self, ParseError> {
ParseError::need("sibling key", 16, key)?;
ParseError::need("sibling", 10, value)?;
let end = 10 + usize::from(get_u16(value, 8));
ParseError::need("sibling name", end, value)?;
let Some((&0, name)) = value[10..end].split_last() else {
return Err(ParseError::Unterminated {
structure: "sibling name",
});
};
Ok(Self {
sibling_id: get_u64(key, 8),
parent_id: get_u64(value, 0),
name,
})
}
}
impl SiblingLink<'_> {
#[must_use]
pub fn to_record(&self, inode: u64) -> (Vec<u8>, Vec<u8>) {
let key = KeyHeader {
id: inode,
kind: record_kind::SIBLING_LINK,
}
.key(&self.sibling_id.to_le_bytes());
let len = u16::try_from(self.name.len() + 1).expect("a name with its NUL fits 16 bits");
let mut value = Vec::with_capacity(10 + self.name.len() + 1);
value.extend_from_slice(&self.parent_id.to_le_bytes());
value.extend_from_slice(&len.to_le_bytes());
value.extend_from_slice(self.name);
value.push(0);
(key, value)
}
}
#[must_use]
pub fn sibling_map_record(sibling: u64, inode: u64) -> (Vec<u8>, Vec<u8>) {
(
KeyHeader {
id: sibling,
kind: record_kind::SIBLING_MAP,
}
.key(&[]),
inode.to_le_bytes().to_vec(),
)
}
pub fn key_u64(key: &[u8], off: usize) -> Result<u64, ParseError> {
ParseError::need("record key", off + 8, key)?;
Ok(get_u64(key, off))
}
#[must_use]
pub const fn split_device(dev: u32) -> (u32, u32) {
(dev >> 24, dev & 0x00FF_FFFF)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_key_header_splits_its_word_into_identifier_and_kind() {
let mut key = [0u8; 8];
KeyHeader {
id: 0x1234,
kind: record_kind::DIR_ENTRY,
}
.write_to(&mut key);
assert_eq!(get_u64(&key, 0), 0x9000_0000_0000_1234);
let header = KeyHeader::read_from(&key).expect("a header");
assert_eq!((header.id, header.kind), (0x1234, 9));
}
#[test]
fn extended_fields_pad_each_field_to_eight_bytes_after_the_descriptors() {
let mut blob = vec![0u8; 12 + 8 + 40];
put_u16(&mut blob, 0, 2);
put_u16(&mut blob, 2, (8 + 40) as u16);
blob[4] = inode_field::NAME;
put_u16(&mut blob, 6, 5);
blob[8] = inode_field::DATA_STREAM;
put_u16(&mut blob, 10, 40);
blob[12..17].copy_from_slice(b"name\0");
put_u64(&mut blob, 20, 4096);
let fields = extended_fields(&blob).expect("frames");
assert_eq!(fields.len(), 2);
assert_eq!(field(&fields, inode_field::NAME), Some(&b"name\0"[..]));
let stream = DataStream::read_from(field(&fields, inode_field::DATA_STREAM).unwrap());
assert_eq!(stream.map(|s| s.size), Ok(4096));
}
#[test]
fn a_field_running_past_its_value_is_refused() {
let mut blob = vec![0u8; 16];
put_u16(&mut blob, 0, 1);
blob[4] = inode_field::DATA_STREAM;
put_u16(&mut blob, 6, 40);
assert!(matches!(
extended_fields(&blob),
Err(ParseError::TooShort { .. })
));
put_u16(&mut blob, 0, 100);
assert!(extended_fields(&blob).is_err());
}
#[test]
fn an_inode_round_trips_with_times_before_1970() {
let inode = InodeValue {
parent_id: 2,
private_id: 20,
create_time: -1,
modify_time: -2_208_988_800_000_000_000,
change_time: 3,
access_time: i64::MAX,
internal_flags: 0x8000,
links_or_children: 1,
protection_class: 0,
write_generation: 0,
bsd_flags: 0,
owner: 501,
group: 20,
mode: 0o100_644,
pad: 0,
uncompressed_size: 0,
};
let mut buf = [0u8; InodeValue::SIZE];
inode.write_to(&mut buf);
assert_eq!(InodeValue::read_from(&buf), Ok(inode));
assert_eq!(get_u16(&buf, 80), 0o100_644, "the mode at 80");
}
#[test]
fn a_directory_entry_key_carries_a_22_bit_hash_and_a_terminated_name() {
let mut key = vec![0u8; 12 + 4];
put_u32(&mut key, 8, (0x3F_FFFF << 10) | 4);
key[12..16].copy_from_slice(b"abc\0");
let entry = EntryKey::read_from(&key).expect("an entry");
assert_eq!(entry.hash, 0x3F_FFFF, "all 22 bits of the hash");
assert_eq!(entry.name, b"abc");
key[15] = b'd';
assert!(matches!(
EntryKey::read_from(&key),
Err(ParseError::Unterminated { .. })
));
put_u32(&mut key, 8, 9);
assert!(matches!(
EntryKey::read_from(&key),
Err(ParseError::TooShort { .. })
));
}
#[test]
fn an_attribute_value_frames_its_data_and_a_stream_its_identifier() {
let mut value = vec![0u8; 4 + 48];
put_u16(&mut value, 0, xattr_flags::STREAM | 0x10);
put_u16(&mut value, 2, 48);
put_u64(&mut value, 4, 77);
put_u64(&mut value, 12, 8000);
let xattr = XattrValue::read_from(&value).expect("frames");
assert_eq!(xattr.stream().map(|(id, s)| (id, s.size)), Ok((77, 8000)));
put_u16(&mut value, 2, 49);
assert!(XattrValue::read_from(&value).is_err());
}
#[test]
fn an_extent_splits_its_length_from_its_flags() {
let mut key = [0u8; 16];
put_u64(&mut key, 8, 8192);
let mut value = [0u8; 24];
put_u64(&mut value, 0, 0x0100_0000_0000_1000);
put_u64(&mut value, 8, 500);
let extent = FileExtent::read_from(&key, &value).expect("an extent");
assert_eq!(
(
extent.logical,
extent.length,
extent.flags,
extent.physical_block
),
(8192, 4096, 1, 500)
);
}
#[test]
fn a_sibling_record_names_the_directory_and_the_name_it_links() {
let mut key = vec![0u8; 16];
put_u64(
&mut key,
0,
20 | (u64::from(record_kind::SIBLING_LINK) << KIND_SHIFT),
);
put_u64(&mut key, 8, 30);
let mut value = vec![0u8; 10];
put_u64(&mut value, 0, 17);
put_u16(&mut value, 8, 6);
value.extend_from_slice(b"hard2\0");
let link = SiblingLink::read_from(&key, &value).expect("a sibling record");
assert_eq!(
(link.sibling_id, link.parent_id, link.name),
(30, 17, &b"hard2"[..])
);
assert!(SiblingLink::read_from(&key, &value[..15]).is_err());
let mut unended = value.clone();
*unended.last_mut().expect("a byte") = b'!';
assert!(matches!(
SiblingLink::read_from(&key, &unended),
Err(ParseError::Unterminated { .. })
));
assert!(SiblingLink::read_from(&key[..12], &value).is_err());
}
#[test]
fn a_darwin_device_number_has_its_major_in_the_top_byte() {
assert_eq!(split_device(0x0300_0004), (3, 4));
assert_eq!(split_device(0x00FF_FFFF), (0, 0x00FF_FFFF));
}
}