boot-tool

boot-tool builds, validates, inspects, verifies, and extracts EriX boot images used by the bootloader and integration pipeline.

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 command-line tool. Its purpose in EriX is to create and inspect the signed boot images consumed by the boot chain and integration harness.

Functionally, it builds, validates, verifies, inspects, and extracts boot.img payloads. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• build signed boot images from kernel, boot-config, service, and blob inputs
• inspect, validate, verify, and extract boot-image payloads for development and CI
• keep boot-image format handling aligned with lib-bootimg and lib-elf

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.

Dependencies

• lib-bootimg (git dependency)
• lib-elf (git dependency)

No external crates are used.

Usage

# Build (kernel + optional early services and non-executable blobs)
boot-tool build \
  --kernel out/kernel.elf \
  --boot-config out/boot-config.bin \
  --early-service rootd:out/rootd.elf \
  --blob console-font:out/console-font.pf2 \
  --output out/boot.img \
  --key-id 0 \
  --build-id-input "ci:job-123"

# Validate structure
boot-tool validate --image out/boot.img

# Inspect image metadata
boot-tool inspect --image out/boot.img

# Verify image authenticity
boot-tool verify \
  --image out/boot.img \
  --pubkey-hex <64-hex-public-key> \
  --key-id 0

# Extract kernel section
boot-tool extract \
  --image out/boot.img \
  --section kernel \
  --output out/kernel.extracted

Build command options

• --kernel <path>: kernel ELF input (required)
• --output <path>: output image path (required)
• --early-service <name:path>: add required early boot service section (repeatable)
• --boot-config <path>: add required boot-config payload section (type=BootConfig)
• --blob <name:path>: add required non-executable blob section (repeatable)
• --key-id <u32>: signature key id (default 0)
• --build-id <hex64>: explicit 32-byte build id
• --build-id-input <string>: append UTF-8 build-id derivation input (repeatable)
• --signature-hex <hex128>: inject 64-byte Ed25519 signature
• --signing-payload-output <path>: write canonical signing payload

Verify command options

• --image <path>: boot image path (required)
• --pubkey-hex <hex64>: 32-byte Ed25519 public key (hex)
• --pubkey-file <path>: raw 32-byte Ed25519 public key file
• --key-id <u32>: expected signature key id (default 0)

Use either --pubkey-hex or --pubkey-file.

Governance Principles

boot-tool governance is scoped to deterministic boot-image construction and inspection on the host.

The scoped governance rules are:

• It must make boot-image layout, signature, and section validation reproducible from explicit inputs.
• It keeps host filesystem access limited to command-line paths supplied by the caller.
• It reports structural and cryptographic failures without silently repairing image contents.
• It follows the lib-bootimg format contract rather than carrying independent image policy.

Host Tool Boundaries

• boot-tool has no runtime kernel authority; its authority is the caller-provided host input/output paths.
• Generated images must remain inspectable and verifiable by the same clean-room format code.

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.