lib-bootimg

lib-bootimg is the validation-first boot image v1 format crate for EriX. It parses, verifies, and constructs deterministic images without performing I/O or selecting boot policy.

EriX is a clean-room, capability-based microkernel operating system written in Rust.

See:

• EriX documentation for the normative boot image format and verification model.
• ARCHITECTURE.md for the component boundary and known implementation constraints.
• ROADMAP.md for current hardening work.

Purpose of This Repository

The crate owns:

• strict parsing of the boot image v1 header, section table, manifest, and signature block
• canonical layout and deterministic construction
• SHA-256 whole-image and per-section verification
• Ed25519 signature verification using a caller-provided trusted public key
• borrowed access to validated section metadata and bytes

The crate does not own:

• file access, image discovery, or boot-device selection
• trusted-key provisioning or key rotation
• required-section, architecture-acceptance, or launch policy
• ELF parsing, mapping, relocation, or process creation
• private-key operations or signing

bootloader consumes the parser and verifier at boot. boot-tool consumes both the builder and verifier for host-side construction and inspection.

Clean-Room Policy

EriX follows a strict clean-room philosophy:

• No external source code may be copied.
• No external Rust crates are allowed.
• No code generation tools may embed third-party code.
• All code must be authored within the project.

The crate depends only on the sibling EriX lib-sha2, lib-ed25519, and lib-constant-time crates. Every Git dependency uses a full 40-character commit rev pin; Integration and CI caches preserve the selected Git object identities.

License

All EriX repositories are licensed under the ISC License.

Development Model

EriX development is modular, deterministic, reproducible, authority-explicit, security-first, and self-hosting oriented.

Current contract

BootImage::parse validates the complete structural representation, including canonical header → section table → manifest → section data → signature order. It walks canonical name and data order directly and retains only borrowed input plus fixed metadata; parsing has no allocator. BootImage::verify_with_key_id then checks the caller-selected key identifier, canonical whole-image hash, every section hash, and the Ed25519 signature. Canonical spans are hashed and authenticated as ordered borrowed fragments without a full-message copy.

Parsing success does not authenticate the bytes. Verification success authenticates the bytes against the caller's key; it does not grant load, mapping, or execution authority.

The builder sorts sections by encoded name, writes all padding and reserved bytes as zero, computes hashes, and exposes the exact canonical signing payload. It writes caller-supplied signature bytes but never obtains a private key.

Example

use bootimg::{BootImage, PublicKey};

fn authenticate(
    bytes: &[u8],
    trusted_key: &PublicKey,
    expected_key_id: u32,
) -> Result<(), bootimg::Error> {
    let image = BootImage::parse(bytes)?;
    image.verify_with_key_id(trusted_key, expected_key_id)?;

    if let Some(kernel) = image.section_by_name("kernel") {
        let _authenticated_kernel = kernel.data(bytes)?;
    }
    Ok(())
}

Every verifier call requires the expected signature key identifier. The library never selects trust policy.

Repository layout

lib-bootimg/
├── src/
│   ├── bootimg/       # Header types, section types, parser, and verifier
│   ├── build.rs       # Deterministic image construction
│   ├── error.rs       # Typed parse, build, and verification errors
│   ├── format.rs      # Shared v1 layout constants
│   ├── lib.rs         # Public API and crate contract
│   └── types.rs       # Public type assembly
├── tests/
│   ├── build_tests.rs
│   └── parse_tests.rs
├── ARCHITECTURE.md
├── README.md
└── ROADMAP.md

Validation

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
RUSTFLAGS="-D warnings" cargo test --all-targets --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features

The current suite covers deterministic construction, canonical signing payloads, structure round trips, key-ID policy, hash mutation, invalid header and manifest fields, metadata-region ordering, section overlap, and bounds.

Governance Principles

• On-disk layout is defined by the normative v1 specification, not by caller convenience.
• Unknown values and noncanonical reserved bytes fail closed.
• Breaking pre-alpha Rust API changes are coordinated with bootloader, boot-tool, tests, and the manual.
• Compatibility aliases with no current consumer are removed.
• Key identifiers and valid signatures are authenticated metadata, not capabilities or launch authority.

Allocation boundary

Parsing and verification require no allocator and retain no storage authority. The optional default builder feature owns host-side Vec output and is disabled by the bootloader. Builder allocation policy therefore remains with host tooling and is absent from the firmware dependency surface.

Contact

Development occurs in the EriX organization. Design decisions require documented rationale. Maintainers can be reached at admin@erikinkinen.fi.