use std::fmt;
pub const PATH: &[u8] = b"/run/hermit/native/catalog";
pub const MAX_BYTES: usize = 1024 * 1024;
pub const MAX_TARGETS: usize = 128;
pub const MAX_OBJECTS: usize = 512;
pub const MAX_EXTENTS: usize = 64;
pub const MAX_PATH: usize = 4095;
pub const MAX_OBJECT_BYTES: u64 = 256 * 1024 * 1024;
pub const MAGIC: [u8; 8] = *b"HLNCAT01";
pub const VERSION: u16 = 2;
pub const HEADER_BYTES: usize = 104;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Bindings {
pub source: [u8; 32],
pub schema: [u8; 16],
pub bootstrap: [u8; 32],
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Extent {
pub start: u64,
pub end: u64,
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Object {
pub device: u64,
pub inode: u64,
pub size: u64,
pub digest: [u8; 32],
pub backing_path: Option<Vec<u8>>,
pub executable: Vec<Extent>,
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Target {
pub path: Vec<u8>,
pub image: u16,
pub stock_loader: u16,
pub runner: u16,
pub native_config: u16,
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Catalog {
pub bindings: Bindings,
pub objects: Vec<Object>,
pub targets: Vec<Target>,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum Error {
Size,
Magic,
Version,
Reserved,
Length,
Binding,
Path,
Object,
Extent,
Role,
Mismatch,
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "native catalog {self:?}")
}
}
impl std::error::Error for Error {}
fn path_valid(path: &[u8]) -> bool {
path.len() > 1
&& path.len() <= MAX_PATH
&& path[0] == b'/'
&& !path.contains(&0)
&& path[1..]
.split(|b| *b == b'/')
.all(|part| !part.is_empty() && part != b"." && part != b"..")
}
impl Catalog {
pub fn validate(&self) -> Result<(), Error> {
let binding = self.bindings;
if binding.source == [0; 32]
|| binding.bootstrap == [0; 32]
|| !binding.schema.iter().all(u8::is_ascii_hexdigit)
{
return Err(Error::Binding);
}
if self.targets.is_empty()
|| self.targets.len() > MAX_TARGETS
|| self.objects.is_empty()
|| self.objects.len() > MAX_OBJECTS
{
return Err(Error::Length);
}
for (i, object) in self.objects.iter().enumerate() {
if object.inode == 0
|| object.size == 0
|| object.size > MAX_OBJECT_BYTES
|| object.digest == [0; 32]
|| self.objects[..i]
.iter()
.any(|other| other.device == object.device && other.inode == object.inode)
{
return Err(Error::Object);
}
if let Some(path) = &object.backing_path
&& (!path_valid(path)
|| path == PATH
|| self.objects[..i]
.iter()
.any(|other| other.backing_path.as_ref() == Some(path)))
{
return Err(Error::Path);
}
if object.executable.len() > MAX_EXTENTS {
return Err(Error::Extent);
}
let limit = object.size.checked_add(4095).ok_or(Error::Extent)? & !4095;
let mut previous = 0;
for extent in &object.executable {
if extent.start % 4096 != 0
|| extent.end % 4096 != 0
|| extent.start < previous
|| extent.start >= extent.end
|| extent.end > limit
{
return Err(Error::Extent);
}
previous = extent.end;
}
}
for (i, target) in self.targets.iter().enumerate() {
if !path_valid(&target.path) || self.targets[..i].iter().any(|t| t.path == target.path)
{
return Err(Error::Path);
}
let indices = [
target.image,
target.stock_loader,
target.runner,
target.native_config,
];
for (i, index) in indices.iter().enumerate() {
if usize::from(*index) >= self.objects.len() || indices[..i].contains(index) {
return Err(Error::Role);
}
}
if [target.image, target.stock_loader, target.runner]
.iter()
.any(|index| self.objects[usize::from(*index)].executable.is_empty())
|| !self.objects[usize::from(target.native_config)]
.executable
.is_empty()
{
return Err(Error::Role);
}
if self.objects[usize::from(target.image)]
.backing_path
.is_none()
{
return Err(Error::Role);
}
}
Ok(())
}
pub fn check_bindings(&self, expected: Bindings) -> Result<(), Error> {
if self.bindings != expected {
return Err(Error::Mismatch);
}
Ok(())
}
}
struct Reader<'a> {
bytes: &'a [u8],
position: usize,
}
impl<'a> Reader<'a> {
fn take<const N: usize>(&mut self) -> Result<[u8; N], Error> {
let end = self.position.checked_add(N).ok_or(Error::Length)?;
let value = self.bytes.get(self.position..end).ok_or(Error::Length)?;
self.position = end;
value.try_into().map_err(|_| Error::Length)
}
fn word(&mut self) -> Result<u16, Error> {
Ok(u16::from_le_bytes(self.take()?))
}
fn wide(&mut self) -> Result<u64, Error> {
Ok(u64::from_le_bytes(self.take()?))
}
fn reserved<const N: usize>(&mut self) -> Result<(), Error> {
if self.take::<N>()? != [0; N] {
return Err(Error::Reserved);
}
Ok(())
}
}
pub fn decode(bytes: &[u8]) -> Result<Catalog, Error> {
if !(HEADER_BYTES..=MAX_BYTES).contains(&bytes.len()) {
return Err(Error::Size);
}
let mut reader = Reader { bytes, position: 0 };
if reader.take::<8>()? != MAGIC {
return Err(Error::Magic);
}
if reader.word()? != VERSION {
return Err(Error::Version);
}
reader.reserved::<2>()?;
if u32::from_le_bytes(reader.take()?) as usize != bytes.len() {
return Err(Error::Size);
}
let bindings = Bindings {
source: reader.take()?,
schema: reader.take()?,
bootstrap: reader.take()?,
};
let targets = usize::from(reader.word()?);
let objects = usize::from(reader.word()?);
reader.reserved::<4>()?;
if targets == 0 || targets > MAX_TARGETS || objects == 0 || objects > MAX_OBJECTS {
return Err(Error::Length);
}
let mut catalog = Catalog {
bindings,
objects: Vec::with_capacity(objects),
targets: Vec::with_capacity(targets),
};
for _ in 0..objects {
let (device, inode, size, digest) = (
reader.wide()?,
reader.wide()?,
reader.wide()?,
reader.take()?,
);
let count = usize::from(reader.word()?);
let path_length = usize::from(reader.word()?);
reader.reserved::<4>()?;
if count > MAX_EXTENTS {
return Err(Error::Extent);
}
if path_length > MAX_PATH {
return Err(Error::Path);
}
let mut executable = Vec::with_capacity(count);
for _ in 0..count {
executable.push(Extent {
start: reader.wide()?,
end: reader.wide()?,
});
}
let backing_path = if path_length == 0 {
None
} else {
let end = reader
.position
.checked_add(path_length)
.ok_or(Error::Length)?;
let path = bytes
.get(reader.position..end)
.ok_or(Error::Length)?
.to_vec();
reader.position = end;
Some(path)
};
catalog.objects.push(Object {
device,
inode,
size,
digest,
backing_path,
executable,
});
}
for _ in 0..targets {
let length = usize::from(reader.word()?);
let (image, stock_loader, runner, native_config) = (
reader.word()?,
reader.word()?,
reader.word()?,
reader.word()?,
);
reader.reserved::<6>()?;
if length == 0 || length > MAX_PATH {
return Err(Error::Path);
}
let end = reader.position.checked_add(length).ok_or(Error::Length)?;
let path = bytes
.get(reader.position..end)
.ok_or(Error::Length)?
.to_vec();
reader.position = end;
catalog.targets.push(Target {
path,
image,
stock_loader,
runner,
native_config,
});
}
if reader.position != bytes.len() {
return Err(Error::Length);
}
catalog.validate()?;
Ok(catalog)
}
pub fn encode(catalog: &Catalog) -> Result<Vec<u8>, Error> {
catalog.validate()?;
let mut length = HEADER_BYTES;
for object in &catalog.objects {
length = length
.checked_add(
64 + object.executable.len() * 16
+ object.backing_path.as_ref().map_or(0, Vec::len),
)
.ok_or(Error::Size)?;
}
for target in &catalog.targets {
length = length
.checked_add(16 + target.path.len())
.ok_or(Error::Size)?;
}
if length > MAX_BYTES {
return Err(Error::Size);
}
let mut bytes = Vec::with_capacity(length);
bytes.extend(MAGIC);
bytes.extend(VERSION.to_le_bytes());
bytes.extend([0; 2]);
bytes.extend((length as u32).to_le_bytes());
bytes.extend(catalog.bindings.source);
bytes.extend(catalog.bindings.schema);
bytes.extend(catalog.bindings.bootstrap);
bytes.extend((catalog.targets.len() as u16).to_le_bytes());
bytes.extend((catalog.objects.len() as u16).to_le_bytes());
bytes.extend([0; 4]);
for object in &catalog.objects {
bytes.extend(object.device.to_le_bytes());
bytes.extend(object.inode.to_le_bytes());
bytes.extend(object.size.to_le_bytes());
bytes.extend(object.digest);
bytes.extend((object.executable.len() as u16).to_le_bytes());
bytes.extend((object.backing_path.as_ref().map_or(0, Vec::len) as u16).to_le_bytes());
bytes.extend([0; 4]);
for extent in &object.executable {
bytes.extend(extent.start.to_le_bytes());
bytes.extend(extent.end.to_le_bytes());
}
if let Some(path) = &object.backing_path {
bytes.extend(path);
}
}
for target in &catalog.targets {
bytes.extend((target.path.len() as u16).to_le_bytes());
for index in [
target.image,
target.stock_loader,
target.runner,
target.native_config,
] {
bytes.extend(index.to_le_bytes());
}
bytes.extend([0; 6]);
bytes.extend(&target.path);
}
debug_assert_eq!(bytes.len(), length);
Ok(bytes)
}
#[cfg(test)]
mod tests {
use super::*;
fn fixture() -> Catalog {
Catalog {
bindings: Bindings {
source: [2; 32],
schema: *b"0123456789abcdef",
bootstrap: [3; 32],
},
objects: (0..4)
.map(|i| Object {
device: 2,
inode: i + 1,
size: 4097,
digest: [i as u8 + 1; 32],
backing_path: (i != 3).then(|| format!("/objects/{i}").into_bytes()),
executable: if i == 3 {
vec![]
} else {
vec![Extent {
start: 0,
end: 8192,
}]
},
})
.collect(),
targets: vec![Target {
path: b"/arbitrary/program".to_vec(),
image: 0,
stock_loader: 1,
runner: 2,
native_config: 3,
}],
}
}
#[test]
fn exact_roundtrip_and_independent_bindings() {
let mut catalog = fixture();
catalog.targets[0].path.push(0xff);
let bytes = encode(&catalog).unwrap();
assert_eq!(&bytes[..8], b"HLNCAT01");
assert_eq!(decode(&bytes).unwrap(), catalog);
let mut expected = catalog.bindings;
expected.source[31] ^= 1;
assert_eq!(catalog.check_bindings(expected), Err(Error::Mismatch));
}
#[test]
fn exact_shape_never_accepts_truncation_or_trailing_data() {
let bytes = encode(&fixture()).unwrap();
for end in 0..bytes.len() {
assert!(decode(&bytes[..end]).is_err());
}
let mut extra = bytes.clone();
extra.push(0);
assert!(decode(&extra).is_err());
for offset in [0, 8, 10, 12, 100, 101, 102, 103] {
let mut wrong = bytes.clone();
wrong[offset] ^= 0x80;
assert!(decode(&wrong).is_err(), "offset {offset}");
}
}
#[test]
fn reference_path_and_executable_extent_negatives() {
for path in [
b"relative".as_slice(),
b"/a/../b",
b"/a//b",
b"/a/.",
b"/a/",
b"/a\0b",
] {
let mut bad = fixture();
bad.targets[0].path = path.to_vec();
assert_eq!(encode(&bad), Err(Error::Path));
}
let mut bad = fixture();
bad.targets.push(bad.targets[0].clone());
assert_eq!(encode(&bad), Err(Error::Path));
let mut bad = fixture();
bad.targets[0].native_config = 0;
assert_eq!(encode(&bad), Err(Error::Role));
let mut bad = fixture();
bad.targets[0].runner = 400;
assert_eq!(encode(&bad), Err(Error::Role));
let mut bad = fixture();
bad.objects[0].executable[0].end = 12288;
assert_eq!(encode(&bad), Err(Error::Extent));
let mut bad = fixture();
bad.objects[0].executable.push(Extent {
start: 4096,
end: 8192,
});
assert_eq!(encode(&bad), Err(Error::Extent));
let mut bad = fixture();
bad.objects[1].inode = bad.objects[0].inode;
assert_eq!(encode(&bad), Err(Error::Object));
}
#[test]
fn backing_paths_preserve_source_identity_and_reject_unbound_roles() {
let original = fixture();
let encoded = encode(&original).unwrap();
assert_eq!(u16::from_le_bytes(encoded[8..10].try_into().unwrap()), 2);
let decoded = decode(&encoded).unwrap();
assert_eq!(decoded.objects[0].device, original.objects[0].device);
assert_eq!(decoded.objects[0].inode, original.objects[0].inode);
assert_eq!(decoded.objects[0].digest, original.objects[0].digest);
for path in [b"/a/../b".as_slice(), b"/a//b", PATH, b"relative", b"/a\0b"] {
let mut bad = original.clone();
bad.objects[0].backing_path = Some(path.to_vec());
assert_eq!(encode(&bad), Err(Error::Path));
}
let mut duplicate = original.clone();
duplicate.objects[1].backing_path = duplicate.objects[0].backing_path.clone();
assert_eq!(encode(&duplicate), Err(Error::Path));
let mut missing = original.clone();
missing.objects[0].backing_path = None;
assert_eq!(encode(&missing), Err(Error::Role));
let mut old = encoded;
old[8..10].copy_from_slice(&1u16.to_le_bytes());
assert_eq!(decode(&old), Err(Error::Version));
}
}