Merge pull request #769 from aidangarske/h5-wolfhsm-port

Add WOLFCRYPT_TZ_WOLFHSM TrustZone engine for STM32H5

Author: dgarske

.github/workflows/test-external-library-paths.yml

@@ -88,4 +88,5 @@ jobs:
             WOLFBOOT_LIB_WOLFSSL="$(realpath ../external-libs/wolfssl)" \
             WOLFBOOT_LIB_WOLFPKCS11="$(realpath ../external-libs/wolfPKCS11)" \
             WOLFBOOT_LIB_WOLFPSA="$(realpath ../external-libs/wolfPSA)" \
-            WOLFBOOT_LIB_WOLFTPM="$(realpath ../external-libs/wolfTPM)"
+            WOLFBOOT_LIB_WOLFTPM="$(realpath ../external-libs/wolfTPM)" \
+            WOLFBOOT_LIB_WOLFHSM="$(realpath ../external-libs/wolfHSM)"

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

@@ -119,6 +119,12 @@ jobs:
           grep -q "\\[BKPT\\] imm=0x7f" /tmp/m33mu-fwtpm.log
           grep -q "\\[EXPECT BKPT\\] Success" /tmp/m33mu-fwtpm.log
 
+      # The wolfHSM STM32H5 TrustZone integration is exercised by the
+      # nightly cross-repo job in wolfHSM
+      # (.github/workflows/wolfboot-tz-integration.yml), which builds
+      # this demo against the latest wolfHSM main and runs it under
+      # m33mu. It is intentionally not gated on every wolfBoot PR.
+
       - name: Clean and build test with DICE attestation + OTP (stm32h5)
         run: |
           make clean distclean

.gitignore

@@ -403,3 +403,6 @@ image.ub
 system-default.dtb
 test_output/
 sdcard.img
+
+# wolfHSM STM32H5 TZ demo build output
+port/stmicro/stm32h5-tz-wolfhsm/out/

Makefile

@@ -218,6 +218,9 @@ OBJS+=$(WOLFCRYPT_OBJS)
 OBJS+=$(PUBLIC_KEY_OBJS)
 OBJS+=$(WOLFHSM_OBJS)
 
+# Vendored wolfHSM sources: keep cosmetic unused-parameter warnings non-fatal
+$(WOLFHSM_OBJS): CFLAGS += -Wno-error=unused-parameter
+
 CFLAGS+= \
   -I"." -I"include/" -I"$(WOLFBOOT_LIB_WOLFSSL)" \
   -Wno-array-bounds \

config/examples/stm32h5-tz-wolfhsm.config

@@ -0,0 +1,38 @@
+ARCH?=ARM
+TZEN?=1
+TARGET?=stm32h5
+SIGN?=ECC256
+HASH?=SHA256
+DEBUG?=0
+VTOR?=1
+CORTEX_M0?=0
+CORTEX_M33?=1
+NO_ASM?=0
+# Required: wolfBoot's mpu_init() (src/boot_arm.c) programs an MPU region for
+# the wolfBoot flash whose layout does not cover this port's secure SRAM, which
+# HardFaults secure boot. Keep the MPU off here until that is handled upstream.
+NO_MPU=1
+EXT_FLASH?=0
+SPI_FLASH?=0
+ALLOW_DOWNGRADE?=0
+NVM_FLASH_WRITEONCE?=1
+WOLFBOOT_VERSION?=1
+V?=0
+SPMATH?=1
+RAM_CODE?=1
+DUALBANK_SWAP?=0
+WOLFBOOT_PARTITION_SIZE?=0xA0000
+WOLFBOOT_SECTOR_SIZE?=0x2000
+WOLFBOOT_KEYVAULT_ADDRESS?=0x0C040000
+WOLFBOOT_KEYVAULT_SIZE?=0x1C000
+WOLFBOOT_NSC_ADDRESS?=0x0C05C000
+WOLFBOOT_NSC_SIZE?=0x4000
+WOLFBOOT_PARTITION_BOOT_ADDRESS?=0x08060000
+WOLFBOOT_PARTITION_UPDATE_ADDRESS?=0x0C100000
+WOLFBOOT_PARTITION_SWAP_ADDRESS?=0x0C1A0000
+FLAGS_HOME=0
+DISABLE_BACKUP=0
+WOLFCRYPT_TZ=1
+WOLFCRYPT_TZ_WOLFHSM=1
+IMAGE_HEADER_SIZE?=1024
+ARMORED=1

docs/STM32-TZ.md

@@ -33,6 +33,19 @@ The `WOLFCRYPT_TZ_PSA` option provides a standard PSA Crypto interface using
 wolfPSA in the secure domain. The key storage uses the same secure flash
 keystore backend as PKCS11, exposed through the wolfPSA store API.
 
+### wolfHSM API in non-secure world
+
+The `WOLFCRYPT_TZ_WOLFHSM` option hosts a wolfHSM server inside the secure
+domain and exposes it to non-secure applications through a single non-secure
+callable veneer. Non-secure code uses the standard wolfCrypt API with the
+wolfHSM client cryptocb registered under `WH_DEV_ID`; key material, the
+keystore, and crypto operations stay in the secure domain. Persistent keys
+live in the same secure flash keystore region used by PKCS11 and PSA, with
+two-partition journaling for power-fail safety.
+
+See [wolfHSM](wolfHSM.md) for the full configuration, build, flash, and
+test recipe on STM32H5.
+
 ### PSA Initial Attestation (DICE)
 
 When `WOLFCRYPT_TZ_PSA=1` is enabled, wolfBoot exposes the PSA Initial

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.
 
@@ -237,3 +238,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
+```
+
+By default the auto-test prints a UART pass/fail line and idles in `while (1)`, which is safe on real silicon. For emulator or under-debugger runs that signal pass/fail via a breakpoint, add `WOLFBOOT_TZ_TEST_BKPT=1` so the auto-test issues `bkpt` instead (this HardFaults on real silicon without a debugger attached):
+
+```sh
+make WOLFBOOT_TZ_TEST_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 prints a final `WOLFHSM_TZ_TEST_PASS` UART line on success. The `WOLFBOOT_TZ_TEST_BKPT=1` 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) instead, for emulator and debugger runs. 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.

include/user_settings.h

@@ -518,6 +518,10 @@ extern int tolower(int c);
         defined(WOLFBOOT_SIGN_ML_DSA)) && \
         !defined(WOLFBOOT_ENABLE_WOLFHSM_SERVER)
         #define WC_NO_RNG
+        /* wolfssl rejects WC_NO_RNG with the default blinding macros.
+         * wolfBoot is verify-only, no blinding is meaningful with a
+         * disabled RNG. */
+        #define WC_BLINDING_NO_RNG_ACKNOWLEDGE_WEAKNESS
     #endif
     #define WC_NO_HASHDRBG
     #define NO_AES_CBC
@@ -571,6 +575,9 @@ extern int tolower(int c);
        defined(WOLFBOOT_SIGN_ML_DSA)) &&          \
       !defined(WOLFBOOT_ENABLE_WOLFHSM_SERVER)
 #   define WC_NO_RNG
+    /* wolfssl rejects WC_NO_RNG with the default blinding macros. wolfBoot
+     * is verify-only, no blinding is meaningful with a disabled RNG. */
+#   define WC_BLINDING_NO_RNG_ACKNOWLEDGE_WEAKNESS
 #   endif
 #   define WC_NO_HASHDRBG
 #   define NO_DEV_RANDOM
@@ -770,12 +777,71 @@ extern int tolower(int c);
 #endif
 
 #if defined(WOLFBOOT_ENABLE_WOLFHSM_CLIENT) || \
-    defined(WOLFBOOT_ENABLE_WOLFHSM_SERVER)
+    defined(WOLFBOOT_ENABLE_WOLFHSM_SERVER) || \
+    defined(WOLFCRYPT_TZ_WOLFHSM)
 #   define WOLF_CRYPTO_CB
 #   undef  HAVE_ANONYMOUS_INLINE_AGGREGATES
 #   define HAVE_ANONYMOUS_INLINE_AGGREGATES 1
 #   define WOLFSSL_KEY_GEN
-#endif /* WOLFBOOT_ENABLE_WOLFHSM_CLIENT || WOLFBOOT_ENABLE_WOLFHSM_SERVER */
+#endif
+
+/* Secure-side sizing common to any wolfHSM server build (TZ engine and
+ * the verify-only cert-chain server). Gated out of host unit tests. */
+#if (defined(WOLFBOOT_ENABLE_WOLFHSM_SERVER) || \
+     defined(WOLFCRYPT_TZ_WOLFHSM)) && !defined(UNIT_TEST)
+    /* Match NS-side WC_MAX_DIGEST_SIZE. NS test-app/wcs/user_settings.h
+     * enables WOLFSSL_SHA3 which sets WC_MAX_DIGEST_SIZE = 64. Without
+     * SHA384/SHA512 on the secure side, WC_MAX_DIGEST_SIZE caps at
+     * SHA256's 32 and wc_ecc_sign_hash (ecc.c:7281) rejects legitimately
+     * oversized hashes (e.g. ECDSA truncation tests) with BAD_LENGTH_E. */
+#   ifndef WOLFSSL_SHA384
+#       define WOLFSSL_SHA384
+#   endif
+#   ifndef WOLFSSL_SHA512
+#       define WOLFSSL_SHA512
+#   endif
+    /* Match the keycache sizing the wolfHSM test suite is validated
+     * against (test/config/wolfhsm_cfg.h: 9 regular + 3 big). The
+     * library defaults (8 + 1) are one regular slot short of the
+     * suite's peak working set and leave too few big slots for the
+     * RSA/ML-DSA cases. */
+#   ifndef WOLFHSM_CFG_SERVER_KEYCACHE_COUNT
+#       define WOLFHSM_CFG_SERVER_KEYCACHE_COUNT 9
+#   endif
+#   ifndef WOLFHSM_CFG_SERVER_KEYCACHE_BIG_COUNT
+#       define WOLFHSM_CFG_SERVER_KEYCACHE_BIG_COUNT 3
+#   endif
+#endif /* WOLFBOOT_ENABLE_WOLFHSM_SERVER || WOLFCRYPT_TZ_WOLFHSM, !UNIT_TEST */
+
+/* AES/HMAC/HKDF are only needed by the STM32H5 TrustZone engine, whose
+ * non-secure client routes general crypto (AES/HMAC/HKDF) through the
+ * secure server. The verify-only cert-chain server does not service these
+ * requests, so it keeps the NO_AES/NO_HMAC set earlier in this file. */
+#if defined(WOLFCRYPT_TZ_WOLFHSM) && !defined(UNIT_TEST)
+#   undef NO_AES
+#   undef NO_HMAC
+#   ifndef WOLFSSL_AES_DIRECT
+#       define WOLFSSL_AES_DIRECT
+#   endif
+#   ifndef HAVE_HKDF
+#       define HAVE_HKDF
+#   endif
+#   ifndef WOLFSSL_AES_COUNTER
+#       define WOLFSSL_AES_COUNTER
+#   endif
+#   ifndef HAVE_AESCTR
+#       define HAVE_AESCTR
+#   endif
+#   ifndef WOLFSSL_AES_GCM
+#       define WOLFSSL_AES_GCM
+#   endif
+#   ifndef HAVE_AESGCM
+#       define HAVE_AESGCM
+#   endif
+#   ifndef GCM_TABLE_4BIT
+#       define GCM_TABLE_4BIT
+#   endif
+#endif /* WOLFCRYPT_TZ_WOLFHSM && !UNIT_TEST */
 
 #if defined(WOLFBOOT_ENABLE_WOLFHSM_SERVER) && \
     defined(WOLFBOOT_CERT_CHAIN_VERIFY)

include/wolfboot/wcs_wolfhsm.h

@@ -0,0 +1,23 @@
+/* wcs_wolfhsm.h
+ *
+ * Copyright (C) 2026 wolfSSL Inc.
+ *
+ * This file is part of wolfBoot.
+ */
+
+#ifndef WOLFBOOT_WCS_WOLFHSM_H
+#define WOLFBOOT_WCS_WOLFHSM_H
+
+#include <stdint.h>
+#include "wolfboot/wc_secure.h"
+
+#ifdef WOLFCRYPT_TZ_WOLFHSM
+
+int CSME_NSE_API wcs_wolfhsm_transmit(const uint8_t *cmd, uint32_t cmdSz,
+        uint8_t *rsp, uint32_t *rspSz);
+
+void wcs_wolfhsm_init(void);
+
+#endif /* WOLFCRYPT_TZ_WOLFHSM */
+
+#endif /* WOLFBOOT_WCS_WOLFHSM_H */

include/wolfboot/wolfhsm_flash_hal.h

@@ -0,0 +1,30 @@
+/* wolfhsm_flash_hal.h
+ *
+ * Copyright (C) 2026 wolfSSL Inc.
+ *
+ * This file is part of wolfBoot.
+ */
+
+#ifndef WOLFBOOT_WOLFHSM_FLASH_HAL_H
+#define WOLFBOOT_WOLFHSM_FLASH_HAL_H
+
+#ifdef WOLFCRYPT_TZ_WOLFHSM
+
+#include <stdint.h>
+
+#include "wolfhsm/wh_flash.h"
+
+/* Per-call config / context for the adapter. base/size/partition_size are
+ * the only client-visible fields; the cache lives inside the static
+ * implementation in wolfhsm_flash_hal.c (mirroring psa_store.c). */
+typedef struct {
+    uint32_t base;
+    uint32_t size;
+    uint32_t partition_size;
+} whFlashH5Ctx;
+
+extern const whFlashCb whFlashH5_Cb;
+
+#endif /* WOLFCRYPT_TZ_WOLFHSM */
+
+#endif /* WOLFBOOT_WOLFHSM_FLASH_HAL_H */