Make native wolfCrypt the default crypto engine and wolfHSM optional

.github/workflows/cross-compile.yml

@@ -33,3 +33,7 @@ jobs:
         run: make -C tests/firmware/stm32h563 all TOOLPREFIX=arm-none-eabi-
       - name: Compile-check the no-attestation secure image (WT_ATTEST_COSE=0)
         run: make TARGET=stm32h563 WT_ATTEST_COSE=0 secure-image TOOLPREFIX=arm-none-eabi-
+      - name: Build the hsm-engine secure image (WT_ENGINE=hsm)
+        run: make TARGET=stm32h563 WT_ENGINE=hsm secure-image TOOLPREFIX=arm-none-eabi- BUILD_DIR=build_hsm
+      - name: Build the native-engine secure image (WT_ENGINE=native)
+        run: make TARGET=stm32h563 WT_ENGINE=native secure-image TOOLPREFIX=arm-none-eabi- BUILD_DIR=build_native

.github/workflows/m33mu.yml

@@ -80,19 +80,21 @@ jobs:
           ./test-app/emu-test-apps/test.sh
 
   wolfboot-wolftrust-m33mu:
-    name: wolfTrust ${{ matrix.guest }} lifecycle
+    name: wolfTrust ${{ matrix.guest }} lifecycle (${{ matrix.engine }})
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
         guest: [zephyr, freertos]
+        engine: [native, hsm]
     timeout-minutes: 45
     container:
       image: ghcr.io/wolfssl/wolfboot-ci-m33mu:v1.15
     env:
       # Keep the validated H5 secure-app handoff until that configuration is
       # upstreamed; upstream master does not yet ship this wolfTrust config.
       WOLFBOOT_REF: d85fa9dbdf6c36f47b7e96eba5c9df750ad3c963
+      WT_ENGINE: ${{ matrix.engine }}
       CROSS_COMPILE: /usr/local/bin/arm-none-eabi-
       ZEPHYR_TOOLCHAIN_VARIANT: cross-compile
       # The wolfBoot configuration reserves the wolfTrust partition at the
@@ -273,11 +275,12 @@ jobs:
           fi
 
   wolfboot-wolftrust-m33mu-scenarios:
-    name: ${{ matrix.scenario.name }}
+    name: ${{ matrix.scenario.name }} (${{ matrix.engine }})
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
+        engine: [native, hsm]
         scenario:
           - { key: positive,        name: "Positive lifecycle" }
           - { key: bothpsa,         name: "Both-OS PSA parity (Zephyr + FreeRTOS)" }
@@ -305,9 +308,17 @@ jobs:
           - { key: vnetneg,         name: "Confined VNET isolation negatives" }
           - { key: manifestneg,     name: "Corrupted-manifest activation refused" }
           - { key: gtzcneg,         name: "NS MPU bypass cannot reach peer guest RAM" }
+          - { key: spbudgetneg,     name: "SP restart-budget exhaustion escalates" }
+        exclude:
+          # hsmattackneg drives the raw wolfHSM client wire from the guest;
+          # the native engine does not link that wire, so the attack surface
+          # under test does not exist there.
+          - { engine: native, scenario: { key: hsmattackneg, name: "wolfHSM cross-namespace + NVM relay negatives" } }
     timeout-minutes: 45
     container:
       image: ghcr.io/wolfssl/wolfboot-ci-m33mu:v1.15
+    env:
+      WT_ENGINE: ${{ matrix.engine }}
     steps:
       - uses: actions/checkout@v4
 

docs/Architecture.md

@@ -21,8 +21,8 @@ contain Armv8-M-specific types and assumptions.
 | wolfBoot | Performs the BL2 secure-boot role, authenticates wolfTrust, passes the measured-boot handoff, and swaps authenticated update images. |
 | wolfTrust | Configures isolation, validates the manifest and guest images, schedules guests and Secure Partitions, implements FF-M IPC, and manages lifecycle and recovery. |
 | wolfPSA | Implements PSA Crypto entry points over wolfCrypt for the Non-secure reference guests. |
-| wolfCrypt | Supplies cryptographic implementations used by wolfPSA and Secure services. |
-| wolfHSM | Owns protected key operations and the persistent NVM backend. |
+| wolfCrypt | Supplies cryptographic implementations used by guest wolfPSA and Secure services. The native engine dispatches it directly. |
+| wolfHSM | Optional crypto engine providing the client/server key-management model and external-HSM integration path. Both engines use its NVM object-store subset. |
 | wolfCOSE | Encodes and signs COSE_Sign1 attestation tokens. |
 | wolfIP | Supplies the TCP/IP stack for the optional bare-metal reference guests; the Secure virtual Ethernet switch itself is implemented by wolfTrust. |
 
@@ -52,9 +52,9 @@ preserve the public manifest, service, IPC, and PSA API contracts. See
    and memory policies; validates and binds the generated manifest; registers
    the FF-M services; seeds each guest context; and performs an initial
    signed-record, image-size, manifest-version, digest, and optional WRP check.
-3. wolfTrust consumes the measured-boot handoff, initializes wolfHSM and the
-   persistent vault backends, and checks the persistent Secure-image and guest
-   version floors.
+3. wolfTrust consumes the measured-boot handoff, initializes the selected
+   [crypto engine](Crypto-Engines.md) and shared persistent vault backend, and
+   checks the persistent Secure-image and guest version floors.
 4. wolfTrust starts the scheduled Secure Partitions.
 5. Immediately before an accepted guest's first dispatch, the monitor repeats
    its signed-record, image-size, manifest-version, digest, and optional WRP

docs/Building.md

@@ -31,6 +31,19 @@ reference is the mutable `main` branch, not a pinned workspace.
 make
 ```
 
+The default uses the native crypto engine. Keep separate output directories
+when comparing or retaining both engine builds:
+
+```sh
+make secure-image WT_ENGINE=native BUILD_DIR=build-native
+make secure-image WT_ENGINE=hsm BUILD_DIR=build-hsm
+```
+
+`WT_ENGINE_HSM=0` and `WT_ENGINE_HSM=1` remain as legacy aliases for
+`native` and `hsm`, respectively. `WT_ENGINE` is the public selector for new
+builds. See [Crypto Engines](Crypto-Engines.md) for the behavior, key model,
+and measured footprint of each choice.
+
 The default target builds:
 
 | Output | Purpose |
@@ -99,6 +112,31 @@ make -C tests/firmware/zephyr-stm32h5 \
     build-guest0-psa build-freertos-guest1
 ```
 
+`WT_ENGINE` must match the Secure image and every guest image. The guest build
+scripts default to `native` and pass the same selector through the Secure and
+guest builds:
+
+```sh
+WT_ENGINE=native make -C tests/firmware/zephyr-stm32h5 \
+    build-guest0-psa build-freertos-guest1
+WT_ENGINE=hsm make -C tests/firmware/zephyr-stm32h5 \
+    build-guest0-psa build-freertos-guest1
+```
+
+For a direct Zephyr configuration rather than the wrapper script:
+
+- native uses `CONFIG_WOLFTRUST_NATIVE_CLIENT=y` and
+  `CONFIG_WOLFTRUST_WOLFHSM_CLIENT=n`; and
+- hsm uses `CONFIG_WOLFTRUST_WOLFHSM_CLIENT=y` and leaves
+  `CONFIG_WOLFTRUST_NATIVE_CLIENT` disabled.
+
+The native Zephyr module links guest wolfCrypt plus
+`src/client/crypto_native_client.c`. The wolfHSM module instead links the
+wolfHSM client, crypto-callback glue, and
+`src/client/hsm_psa_transport.c`. The FreeRTOS
+`build_freertos_guest.sh` script makes the same source and preprocessor choice
+from its `WT_ENGINE` environment variable.
+
 This produces:
 
 - `tests/firmware/zephyr-stm32h5/build/guest0_psa/zephyr/zephyr.bin`
@@ -117,6 +155,19 @@ The same Makefile also provides:
 | `run-tui` | Same pair with the M33MU TUI |
 | `zephyr-freertos-uarts` | Zephyr and FreeRTOS PSA guests under M33MU |
 
+## Engine coverage in CI
+
+The cross-compile workflow links a Secure image with each engine. The M33MU
+lifecycle job crosses `guest: [zephyr, freertos]` with
+`engine: [native, hsm]`. The scenario job also adds the engine as a matrix
+dimension, and the label-selected pull-request workflow runs each requested
+scenario under both engines.
+
+The `hsmattackneg` scenario is intentionally hsm-only. It injects raw wolfHSM
+protocol packets and attacks a wolfHSM namespace and NVM relay surface that is
+not linked into the native engine. All other scenario rows run under both
+engines. See [Testing](Testing.md) for the commands and validation scope.
+
 ## Authenticated image assembly
 
 `make` alone produces an unsigned flat Secure binary. The target