Add a generic secure application handoff for authenticated boot

[aidangarske]

on trustzone-m devices wolfboot currently can only hand control to a non-secure applciation. There is no built-in way to launch a signed Secure-state runtime (a secure OS or TF-M-style secure world) and pass it a trustworthy measurement of the image that was booted, so anyone needing that has had to patch wolfBoot out of tree. This adds WOLFBOOT_SECURE_APP, a target-independent measured handoff that authenticates the image writes its SHA-256 measurement to a known secure-RAM address for the runtime to consume, and jumps while staying in Secure state. It works on any Armv8-M TrustZone target through config alone.

• Adds WOLFBOOT_SECURE_APP so wolfBoot hands off to a signed Secure-state runtime (e.g. a TrustZone-M Secure app) instead of a
  Non-secure app, staying in Secure state.
• Before jumping, wolfBoot authenticates and measures the booted image and writes a 56-byte record (magic and inverse, version,
  PSA lifecycle, image version, SHA-256 measurement) to WOLFBOOT_SECURE_HANDOFF_ADDRESS.
• The record is written torn-write-safe (fields first, magic last, fenced) so a consumer observes a complete record or none.
• Target-independent: the address comes from config (compile error if unset), signed images and SHA-256 are required, and
  SIGN=NONE / WOLFBOOT_NO_SIGN / WOLFBOOT_SKIP_BOOT_VERIFY are rejected.
• A new port needs only the two config values, an optional weak hal_attestation_get_lifecycle, and its own TrustZone setup keeping
  the secure app Secure across the jump.
• STM32H5 is the reference consumer (config/examples/stm32h5-tz-wolftrust.config, record at 0x30020000; lifecycle from flash
  product state and debug auth status).
• No behavior change when WOLFBOOT_SECURE_APP is unset; existing boot paths are untouched.
• Tested: host unit tests unit-secure-handoff.c and test-secure-handoff-config.sh pass.
• Tested: STM32H5 M33MU full 26-scenario wolfTrust chain matrix green (positive, FF-M conformance 85/4, dev_apis
  crypto/storage/attestation, isolation negatives, anti-rollback, boot-and-update).
• Tested: STM32H5 silicon boot with the measured handoff consumed (attestation token measurement equals the signed image).

[Copilot]

Copilot review overview

🟡 Changes recommended

Three unresolved moderate findings remain regarding header coupling, interrupt masking, and updater-path coverage.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Public record header incorrectly depends on internal hash macro · New

What changed in this PR

Adds an opt-in TrustZone-M secure application handoff with authenticated SHA-256 measurement and lifecycle metadata, including STM32H5 support.

Changes:

• Adds the secure handoff record and measured Secure-state boot path.
• Adds configuration validation, lifecycle handling, documentation, and tests.
• Adds STM32H5 reference configuration and TrustZone integration.

File	Summary
tools/​unit-tests/​unit-secure-handoff.c	Tests handoff record construction and lifecycle mapping.
tools/​unit-tests/​test-secure-handoff-config.sh	Tests configuration validation and stack settings.
tools/​unit-tests/​Makefile	Registers secure handoff tests.
tools/​config.mk	Adds secure handoff configuration variables.
src/​update_flash.c	Builds and publishes the handoff record; moderate finding, 1 vote.
src/​boot_arm.c	Adds Secure-state application branching; moderate finding, 1 vote.
options.mk	Adds secure handoff validation and build settings.
Makefile	Adjusts STM32H5 build targets.
include/​wolfboot/​wolfboot.h	Adds secure-app configuration checks.
include/​wolfboot/​secure_handoff.h	Defines the handoff ABI; moderate finding, 2 votes.
hal/​stm32h5.h	Adds STM32H5 product-state definitions.
hal/​stm32h5.c	Implements lifecycle reporting and handoff setup.
hal/​stm32h5_lifecycle.h	Maps STM32H5 states to PSA lifecycle values.
hal/​stm32_tz.c	Preserves Secure memory and flash regions.
docs/​secure_app_handoff.md	Documents configuration, record format, and porting.
config/​examples/​stm32h5-tz-wolftrust.config	Adds the STM32H5 reference configuration.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.