boot-tool

boot-tool builds, inspects, structurally validates, authenticates, and extracts EriX boot.img artifacts 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, bootloader, libraries, and integration tooling.

Purpose of This Repository

This repository owns the host command-line interface to the lib-bootimg format. It does not independently implement the format and does not hold an Ed25519 private key.

The maintained responsibilities are:

• assemble a canonical image from explicitly named input files
• export the canonical signing payload for an external signer
• inject a caller-supplied detached signature into a rebuilt image
• inspect or structurally validate image metadata
• authenticate image and section bytes with a caller-supplied public key
• extract one explicitly named section

Kernel and early-service inputs are opaque bytes. boot-tool does not perform host-side ELF validation; the bootloader validates executable structure before loading.

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, pinned by a full 40-character commit rev

No external crates are used.

Build and detached-signing workflow

Without --signature-hex, build emits a structurally valid image whose signature bytes are zero. That image is not authenticated. A signed build is a two-pass workflow:

# 1. Build the canonical unsigned image and export exactly what must be signed.
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 \
  --build-id-input "ci:job-123" \
  --signing-payload-output out/boot.signing-payload \
  --output out/boot.unsigned.img

# 2. Sign out/boot.signing-payload with an external Ed25519 signer and encode
#    the resulting 64 bytes as 128 hexadecimal characters.

# 3. Rebuild from the same inputs and inject those detached signature bytes.
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 \
  --build-id-input "ci:job-123" \
  --signature-hex <128-hex-signature> \
  --output out/boot.img

# 4. Authenticate the complete image.
boot-tool verify \
  --image out/boot.img \
  --pubkey-hex <64-hex-public-key> \
  --key-id 0

The two builds must receive identical section and build-ID inputs. build rejects a simultaneous explicit --build-id and derived --build-id-input configuration.

Other commands

# Display structurally parsed metadata.
boot-tool inspect --image out/boot.img

# Check structure without authenticating hashes or the signature.
boot-tool validate --image out/boot.img

# Authenticate and extract from the same in-memory image bytes.
boot-tool extract \
  --image out/boot.img \
  --section kernel \
  --output out/kernel.extracted \
  --pubkey-file trusted-ed25519.pub \
  --key-id 0

# Deliberately bypass authentication for forensic inspection.
boot-tool extract-unverified \
  --image out/boot.img \
  --section kernel \
  --output out/kernel.unverified

inspect, validate, and extract-unverified do not authenticate an image. Their output is untrusted. extract verifies the same bytes from which it publishes the section, avoiding a verify-then-reopen replacement gap.

Build command options

• --kernel <path>: opaque kernel input, required
• --output <path>: image output, required
• --early-service <name> <path>: required executable service section, repeatable
• --blob <name> <path>: required non-executable blob section, repeatable
• --boot-config <path>: required boot-config section
• --key-id <u32>: signature key ID, default 0
• --build-id <hex64>: explicit 32-byte manifest build ID
• --build-id-input <string>: ordered UTF-8 build-ID derivation input, repeatable
• --signature-hex <hex128>: detached 64-byte Ed25519 signature
• --signing-payload-output <path>: canonical detached-signing payload output

Section names must satisfy the boot-image format: non-empty ASCII strings of at most 15 bytes. Section storage is sorted by name, while repeated build-ID inputs remain order-sensitive. Paths use the host's native path representation and are not restricted to UTF-8.

Scalar options are accepted once. Ambiguous duplicates and conflicting build-ID modes are usage errors. Complete outputs are written to adjacent temporary files, synchronized, and atomically renamed into place. When a build emits both a signing payload and an image, it publishes the final image last.

Verify command options

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

Exactly one public-key source is required.

Dynamic boot-image evidence

Use authenticated extraction for dynamic-link evidence:

boot-tool verify --image out/boot.img --pubkey-file trusted-ed25519.pub
boot-tool inspect --image out/boot.img
boot-tool extract \
  --image out/boot.img \
  --section dynlink-img \
  --output out/dynlink-img.toml \
  --pubkey-file trusted-ed25519.pub
boot-tool extract \
  --image out/boot.img \
  --section dynlink-store \
  --output out/dynlink-store.pkg \
  --pubkey-file trusted-ed25519.pub

A dynamic image may contain dynlink-img, dynlink-early, dynlink-objs, and dynlink-store. Those sections are packaged evidence, not runtime lookup authority.

Governance Principles

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

The scoped governance rules are:

• The tool reads and writes only paths supplied in the invocation.
• It does not discover configuration, keys, or inputs from the environment, home directory, network, or system paths.
• Structural parsing is never described as authentication.
• Image-format policy remains in lib-bootimg.
• Build and verification diagnostics do not expose private signing material; the tool never receives a private signing key.
• Exit status 2 identifies invocation errors; status 1 identifies filesystem, format, build, or authentication failures.

Host Tool Boundaries

The process inherits the host filesystem authority of its launcher. The CLI narrows normal operation to caller-supplied paths, but it is not an OS capability sandbox. Because its output enters the boot supply chain, boot-tool, its dependency, and the surrounding build environment are part of the build-artifact integrity boundary; none becomes runtime kernel authority.

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.