lib-bootimg

lib-bootimg a small, validation-first boot.img format crate for the EriX project, written in Rust.

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

Technical requirements are tracked in the EriX requirements, conventions, and project documentation.

See:

• docs for design documents, specifications, and development plans.
• Related architecture repositories for kernel, services, libraries, drivers, and integration tooling.

Purpose of This Repository

This repository implements the EriX boot-image library. Its purpose in EriX is to provide reusable boot-image primitives and contracts to EriX components.

Functionally, it exposes the boot-image APIs, validation tests, and documentation used by dependent repositories. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• expose the lib-bootimg crate API for boot-image behavior used by dependent components
• keep data formats, constants, and validation helpers documented and tested
• preserve clean-room, no-external-crate implementation boundaries
• maintain compatibility expectations for downstream repositories

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 that embed third-party code.
• All code must be authored within the project.

Violations will result in rejection of the contribution.

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.

This repository follows the project roadmap and the validation rules documented in its own roadmap.

Example (intended usage)

Note: exact names may evolve while the API is being finalized.

use bootimg::{BootImage, PublicKey};

fn verify_and_load(
    bytes: &[u8],
    pubkey: &PublicKey,
) -> Result<(), bootimg::Error> {
    // Parse and validate structure
    let img = BootImage::parse(bytes)?;

    println!("boot.img version: {}", img.version());
    println!("sections: {}", img.section_count());

    // Verify cryptographic integrity
    img.verify(pubkey)?;
    // Optional key policy:
    // img.verify_with_key_id(pubkey, expected_key_id)?;

    // Access sections
    for section in img.sections() {
        println!(
            "section '{}': offset=0x{:x} size=0x{:x}",
            section.name(),
            section.offset(),
            section.size(),
        );

        // Borrowed bytes for this section
        let data = section.data(bytes)?;
        println!("  data: {} bytes", data.len());
    }

    // Extract kernel section
    if let Some(kernel) = img.section_by_name("kernel")? {
        let kernel_bytes = kernel.data(bytes)?;
        println!("kernel ready: {} bytes", kernel_bytes.len());
    }

    Ok(())
}

Testing strategy

This repo prefers deterministic, authored tests:

• Hand-authored fixtures (valid boot.img samples, built as part of testing).
• Negative tests for each validation rule:
  • Bad magic
  • Invalid version
  • Misaligned sections
  • Out-of-bounds offsets
  • Overflow cases
  • Signature mismatches
  • Hash mismatches
• Optional internal mutation harnesses (randomized corruption) as smoke tests.

Repository layout

lib-bootimg/
├── src/
│   ├── lib.rs          # Public API
│   ├── parse.rs        # Read path: structure parsing
│   ├── verify.rs       # Read path: cryptographic verification
│   ├── build.rs        # Build path: deterministic image construction
│   ├── error.rs        # Error types
│   └── ...
├── tests/
│   ├── valid_images/   # Known-good test fixtures
│   └── invalid_images/ # Negative test cases
├── ARCHITECTURE.md     # Component architecture
├── README.md           # This file
└── ...

Dependencies

This crate uses sibling EriX crypto crates:

• lib-sha2 (SHA-256)
• lib-ed25519 (Ed25519 verification)
• lib-constant-time (timing-safe comparisons)

See: ../../docs/policies/no-external-code.md

Current status

Implemented baseline.

Read/verify/build paths are implemented and exercised by tests. Current work is focused on hardening coverage and broader cross-repo integration fixtures.

See: ROADMAP.md for planned milestones.

Governance Principles

lib-bootimg governance is scoped to reusable boot-image contracts shared by dependent repositories.

The scoped governance rules are:

• It must expose narrow, documented APIs rather than component-specific policy.
• It keeps wire formats, constants, parsers, and validation helpers deterministic and testable.
• It preserves clean-room implementation boundaries and does not introduce external crate dependencies.
• Breaking API or format changes require coordinated updates in every dependent repository.

Library Boundaries

• lib-bootimg carries no runtime authority by itself; authority is held by callers that use the library.
• The crate must not hide ambient I/O, allocation policy, or service discovery behind helper APIs.

Contact

Development occurs in EriX organization and discussions happen in issues and design documents.

No decisions are considered valid without documented rationale.

Maintainers can be reached via email: admin@erikinkinen.fi.