Skip to content

factory_provisioning.md

Latest commit

 

History

History
135 lines (100 loc) · 4.76 KB

factory_provisioning.md

File metadata and controls

135 lines (100 loc) · 4.76 KB
Raw

Factory Provisioning Workflow

This workflow describes the software artifacts needed to bring a freshly erased STM32F429IGT6 device to its first verified Slot A boot. It does not perform hardware flashing, option-byte programming, WRP, RDP, or irreversible provisioning.

Security Boundary

Boot metadata is not an authenticity mechanism. It selects the active and candidate slots and records lifecycle state. Stage 0 still boots only after the compiled Ed25519 public key verifies the signed image manifest, payload SHA-512, vector table, MSP, reset handler, and slot bounds.

The initial metadata record is generated by the host provisioning utility built from the same C implementation used by Stage 0. The utility calls boot_metadata_empty(), boot_metadata_prepare_next(), and boot_metadata_encode(). It does not duplicate metadata CRC, serialization, or validation rules in Python.

Inputs

Required inputs:

  • EXP045 Stage-0 bootloader artifact for stm32f429_1m
  • Slot A signed application image whose payload vector base is 0x08020200
  • initial image version to record as confirmed metadata
  • trusted public key already compiled into Stage 0
  • a controlled hardware programming procedure reviewed separately

The initial image version must match the signed Slot A application version used as the factory confirmed image. Version 0 is invalid for committed confirmed metadata.

Build And Verify Artifacts

Build the bootloader and Slot A application with the hardware-validation layout:

make -C firmware/exp045_bootloader_v2 clean all report LAYOUT_PROFILE=stm32f429_1m
make -C firmware/exp066_research_platform_core SLOT=a clean all \
  update-package inspect-update-package verify-update-package \
  LAYOUT_PROFILE=stm32f429_1m \
  SIGNING_SEED=/path/to/release_signing_seed.bin \
  PUBLIC_KEY_HEADER=../exp045_bootloader_v2/src/firmware_public_key.h

The Slot A update-slot package must be written at the Slot A signed-image base: 0x08020000. Its manifest format version is 2, its target compatibility is 0xf429ab01, its image type is application, and its vector table is at 0x08020200.

Create Initial CONFIRMED Metadata

Build the host provisioning tool:

make -C tools boot-metadata-provision

Create deterministic redundant metadata records:

mkdir -p build/factory
tools/build/boot_metadata_provision.bin create-confirmed \
  --slot a \
  --image-version <initial-image-version> \
  --copy-a-output build/factory/boot_metadata_a.bin \
  --copy-b-output build/factory/boot_metadata_b.bin \
  --json-output build/factory/boot_metadata_provision.json

For workflows that require full metadata-sector images, add --sector-image. The first 128 bytes contain the canonical committed record and the rest of each sector image is 0xff.

Expected metadata addresses:

  • copy A: 0x08008000
  • copy B: 0x0800c000

Both copies are intentionally identical at sequence 1. Recovery treats equal and identical copies as deterministic and selects copy A. Later metadata commits alternate to the other copy through boot_metadata_commit().

Programming Order

The controlled hardware programming procedure should program only these regions:

  • Stage 0 at 0x08000000
  • Slot A signed image at 0x08020000
  • boot metadata copy A at 0x08008000
  • boot metadata copy B at 0x0800c000

Metadata sectors must be erased before programming the generated metadata records or sector images. Do not write Stage 0, metadata, recovery, option bytes, OTP, or protection settings outside the reviewed procedure.

First Boot After Mass Erase

A freshly erased device has no valid metadata copies. Stage 0 must fail closed and must not guess a boot slot.

After Slot A and both metadata copies are provisioned:

  1. Stage 0 recovers the redundant metadata.
  2. Metadata state is CONFIRMED.
  3. Active slot is Slot A.
  4. Stage 0 verifies the Slot A signed image.
  5. Stage 0 transfers control only if image verification succeeds.

If Slot A verification fails, Stage 0 fails closed even when metadata is valid.

Lifecycle After Factory Provisioning

Normal updates preserve the existing lifecycle:

CONFIRMED -> WRITING -> CANDIDATE_READY
CANDIDATE_READY -> PENDING_TRIAL
PENDING_TRIAL -> PENDING_TRIAL
PENDING_TRIAL -> CONFIRMED
PENDING_TRIAL -> REJECTED_INVALID
REJECTED_INVALID -> WRITING

Update installation verifies the package before erase where possible, writes only the inactive slot through boot_flash, verifies the installed image, and commits CANDIDATE_READY. Stage 0 owns trial boot attempt accounting. Application confirmation is idempotent and can confirm only the currently booted pending slot.

Rollback to the last confirmed slot remains metadata-driven. Hardware-backed rollback counters, WRP, RDP, and option-byte provisioning remain separate, deferred hardware-validation work.