Phase 4: docs/wolfHSM.md TZ section + CI lane for stm32h5-tz-wolfhsm

  - docs/wolfHSM.md: append a STM32H5 TrustZone Engine section
    alongside the simulator section. Covers build (incl.
    WOLFBOOT_TZ_TEST_NO_BKPT for hardware), flashing via
    set-stm32-tz-option-bytes.sh + STM32_Programmer_CLI, expected UART
    output for both boots, and notes the H5 quad-word ECC handling
    shared with psa_store / pkcs11_store. Existing client/server
    content untouched.
  - .github/workflows/trustzone-emulator-tests.yml: add a wolfHSM step
    that mirrors the PKCS11 first/second-boot pattern -- one m33mu
    --persist run with --expect-bkpt 0x7d after the first boot path,
    committing key to NVM message, then a second --persist run with
    --expect-bkpt 0x7f after the restored persisted key message.

Author: aidangarske

.github/workflows/trustzone-emulator-tests.yml

@@ -119,6 +119,52 @@ jobs:
           grep -q "\\[BKPT\\] imm=0x7f" /tmp/m33mu-fwtpm.log
           grep -q "\\[EXPECT BKPT\\] Success" /tmp/m33mu-fwtpm.log
 
+      - name: Clean and build test with wolfHSM (stm32h5)
+        run: |
+          make clean distclean
+          cp config/examples/stm32h5-tz-wolfhsm.config .config
+          make
+
+      - name: Prepare wolfHSM persistence directory
+        run: |
+          rm -rf /tmp/m33mu-wolfhsm-persist
+          mkdir -p /tmp/m33mu-wolfhsm-persist
+          rm -f /tmp/m33mu-wolfhsm-first.log /tmp/m33mu-wolfhsm-second.log
+
+      - name: Run wolfHSM first boot (stm32h5)
+        run: |
+          cd /tmp/m33mu-wolfhsm-persist
+          m33mu "$GITHUB_WORKSPACE/wolfboot.bin" \
+            "$GITHUB_WORKSPACE/test-app/image_v1_signed.bin:0x60000" \
+            --persist --uart-stdout --timeout 120 --expect-bkpt 0x7d \
+            | tee /tmp/m33mu-wolfhsm-first.log
+
+      - name: Verify wolfHSM first boot (stm32h5)
+        run: |
+          grep -q "wolfHSM CommInit ok" /tmp/m33mu-wolfhsm-first.log
+          grep -q "wolfHSM RNG ok:" /tmp/m33mu-wolfhsm-first.log
+          grep -q "wolfHSM SHA256 ok" /tmp/m33mu-wolfhsm-first.log
+          grep -q "wolfHSM AES ok" /tmp/m33mu-wolfhsm-first.log
+          grep -q "wolfHSM first boot path, committing key to NVM" /tmp/m33mu-wolfhsm-first.log
+          grep -q "wolfHSM NSC tests passed" /tmp/m33mu-wolfhsm-first.log
+          grep -q "\\[BKPT\\] imm=0x7d" /tmp/m33mu-wolfhsm-first.log
+          grep -q "\\[EXPECT BKPT\\] Success" /tmp/m33mu-wolfhsm-first.log
+
+      - name: Run wolfHSM second boot (stm32h5)
+        run: |
+          cd /tmp/m33mu-wolfhsm-persist
+          m33mu "$GITHUB_WORKSPACE/wolfboot.bin" \
+            "$GITHUB_WORKSPACE/test-app/image_v1_signed.bin:0x60000" \
+            --persist --uart-stdout --timeout 120 --expect-bkpt 0x7f \
+            | tee /tmp/m33mu-wolfhsm-second.log
+
+      - name: Verify wolfHSM second boot (stm32h5)
+        run: |
+          grep -q "wolfHSM second boot path, restored persisted key" /tmp/m33mu-wolfhsm-second.log
+          grep -q "wolfHSM NSC tests passed" /tmp/m33mu-wolfhsm-second.log
+          grep -q "\\[BKPT\\] imm=0x7f" /tmp/m33mu-wolfhsm-second.log
+          grep -q "\\[EXPECT BKPT\\] Success" /tmp/m33mu-wolfhsm-second.log
+
       - name: Clean and build test with DICE attestation + OTP (stm32h5)
         run: |
           make clean distclean

docs/wolfHSM.md

@@ -21,6 +21,7 @@ wolfBoot supports using wolfHSM on the following platforms:
 
 - wolfBoot simulator (using wolfHSM POSIX TCP transport)
 - AURIX TC3xx (shared memory transport)
+- STM32H5 TrustZone (the secure-side wolfBoot hosts a wolfHSM server and exposes it to the non-secure application through a single NSC veneer; see [STM32H5 TrustZone Engine](#stm32h5-trustzone-engine) below)
 
 Details on configuring wolfBoot to use wolfHSM on each of these platforms can be found in the wolfBoot (and wolfHSM) documentation specific to that target, with the exception of the simulator, which is documented here. The remainder of this document focuses on the generic wolfHSM-related configuration options.
 
@@ -238,3 +239,51 @@ When using wolfHSM server mode, no external server is required. wolfBoot include
 ```
 
 The embedded wolfHSM server will automatically handle all cryptographic operations and key management using the file-based NVM storage(`wolfBoot_wolfHSM_NVM.bin`) that was generated above.
+
+## STM32H5 TrustZone Engine
+
+On STM32H5, wolfBoot can host a wolfHSM server in the secure TrustZone image and expose it to the non-secure application through a single non-secure-callable veneer (`wcs_wolfhsm_transmit`). The non-secure side runs the standard wolfHSM client API, which auto-registers a wolfCrypt cryptocb under `WH_DEV_ID`, so application-level wolfCrypt calls that pass that device ID transparently round-trip to the secure server.
+
+This is a separate deployment shape from the wolfHSM client/server modes documented above; it does not use `WOLFBOOT_ENABLE_WOLFHSM_CLIENT/SERVER` or the `hsmClientCtx`/`hsmServerCtx` HAL hooks, and is mutually exclusive with the other STM32H5 TrustZone engines (`WOLFCRYPT_TZ_PKCS11`, `WOLFCRYPT_TZ_PSA`, `WOLFCRYPT_TZ_FWTPM`).
+
+### Build
+
+```sh
+cp config/examples/stm32h5-tz-wolfhsm.config .config
+make
+```
+
+For on-board hardware testing, add `WOLFBOOT_TZ_TEST_NO_BKPT=1` so the auto-test prints a UART pass/fail line and idles in `while (1)` instead of issuing `bkpt #0x7f` (which HardFaults on real silicon without a debugger):
+
+```sh
+make WOLFBOOT_TZ_TEST_NO_BKPT=1
+```
+
+### Flash
+
+The wolfBoot helper programs the option bytes the secure boot path requires (`TZEN`, `SECBOOTADD`, `SECWM1`/`SECWM2`); see [STM32-TZ.md](STM32-TZ.md) for the option-byte details:
+
+```sh
+./tools/scripts/set-stm32-tz-option-bytes.sh
+STM32_Programmer_CLI -c port=swd -d wolfboot.bin 0x0C000000
+STM32_Programmer_CLI -c port=swd -d test-app/image_v1_signed.bin 0x08060000
+```
+
+### Test
+
+The non-secure test application runs the wolfHSM auto-test at startup. A successful first boot ends with:
+
+```text
+wolfHSM CommInit ok (client=1 server=...)
+wolfHSM RNG ok: <16 random bytes>
+wolfHSM SHA256 ok
+wolfHSM AES ok
+wolfHSM first boot path, committing key to NVM
+wolfHSM NSC tests passed
+```
+
+The default build raises `bkpt #0x7d` on first-boot success and `bkpt #0x7f` on second-boot success (after the persisted key is reloaded from flash on reset). The `WOLFBOOT_TZ_TEST_NO_BKPT=1` build prints a final `WOLFHSM_TZ_TEST_PASS` UART line instead. Reset the board (no re-flash) to verify persistence; the second boot prints `wolfHSM second boot path, restored persisted key`.
+
+### Notes
+
+The wolfHSM NVM lives in the existing `FLASH_KEYVAULT` region (112 KiB at `0x0C040000`) shared with the other STM32H5 TrustZone engines. The flash adapter (`src/wolfhsm_flash_hal.c`) caches the affected sector, modifies it, and rewrites the whole 8 KiB sector in one erase + program cycle, mirroring `psa_store.c` / `pkcs11_store.c`. This satisfies the H5 quad-word ECC rule that each 16-byte unit may be programmed exactly once between erases, which wolfHSM's 8-byte-unit writes would otherwise violate.