port/armv8m-tz: NSC bridge transport for ARMv8-M TrustZone

aidangarske · aidangarske · commit 16cfc435f5b4 · 2026-05-12T09:54:48.000-07:00
Rename port/stmicro/stm32-tz to port/armv8m-tz to reflect that the
transport is target-agnostic across ARMv8-M parts (Cortex-M23/M33/
M35P/M55/M85). The target-specific NSC veneer is provided by the
host; the only ARM-flavored thing in the transport is the documented
expectation that the extern wcs_wolfhsm_transmit symbol is a
cmse_nonsecure_entry on the secure side.

Config define renamed WOLFHSM_CFG_PORT_STM32_TZ_NSC -&gt;
WOLFHSM_CFG_PORT_ARMV8M_TZ_NSC and make flag STM32_TZ_NSC=1 -&gt;
ARMV8M_TZ_NSC=1. wh_settings.h doc, chapter08 port docs, and the
CI step name all updated to drop STM32-specific wording.

Review fixes folded in:

- _NscServerRecv clears ctx-&gt;rsp_size up-front so error paths leave
  no stale response state behind.
- _NscClientRecv rejects too-small caller buffers with WH_ERROR_BADARGS
  instead of WH_ERROR_ABORTED; cached response is preserved for retry.
- _NscClientSend returns WH_ERROR_NOTREADY if a prior response has not
  been consumed; propagates known WH_ERROR_* codes from the veneer.
- _NscServerCleanup zeroes the context so stale NS pointers cannot
  survive a reinit.
- Reorder whTransportNscServerContext fields to satisfy -Wpadded.
- Cover the new behaviors in wh_test_transport_nsc and add the NSC
  contexts to the struct padding check.
diff --git a/.github/workflows/build-and-test.yml b/.github/workflows/build-and-test.yml
@@ -36,9 +36,9 @@ jobs:
     - name: Build and test
       run: cd test && make clean && make -j WOLFSSL_DIR=../wolfssl && make run
 
-    # Build and test STM32 TrustZone NSC bridge transport (port/stmicro/stm32-tz)
-    - name: Build and test STM32_TZ_NSC ASAN
-      run: cd test && make clean && make -j STM32_TZ_NSC=1 ASAN=1 WOLFSSL_DIR=../wolfssl && make run
+    # Build and test ARMv8-M TrustZone NSC bridge transport (port/armv8m-tz)
+    - name: Build and test ARMV8M_TZ_NSC ASAN
+      run: cd test && make clean && make -j ARMV8M_TZ_NSC=1 ASAN=1 WOLFSSL_DIR=../wolfssl && make run
 
     # Build and test standard build, with DMA and ASAN enabled
     - name: Build and test DMA ASAN
diff --git a/docs/src/chapter08.md b/docs/src/chapter08.md
@@ -46,15 +46,15 @@ The distribution of this  port is restricted by the vendor. Please contact suppo
 - 1x 100MHz e200z0 PowerPC HSM core with NVM
 - Crypto offload: TRNG, AES128
 
-### STM32 TrustZone (STM32H5 / NSC bridge)
+### ARMv8-M TrustZone (NSC bridge)
 
-The `port/stmicro/stm32-tz` port provides a synchronous TrustZone non-secure-callable bridge transport for ARMv8-M Cortex-M targets. It is designed for the wolfBoot deployment in which the secure-side wolfBoot image hosts a wolfHSM server and exposes it to the non-secure application through a single `cmse_nonsecure_entry` veneer (`wcs_wolfhsm_transmit`); see `wolfBoot/docs/wolfHSM.md` for the build, flash, and test recipe on STM32H5.
+The `port/armv8m-tz` port provides a synchronous TrustZone non-secure-callable bridge transport for any ARMv8-M Cortex-M target (Cortex-M23 / M33 / M35P / M55 / M85). It is designed for deployments in which a secure-side image hosts a wolfHSM server and exposes it to the non-secure application through a single `cmse_nonsecure_entry` veneer (`wcs_wolfhsm_transmit`). The first integration is wolfBoot on STM32H5; see `wolfBoot/docs/wolfHSM.md` for the build, flash, and test recipe.
 
 The port provides:
 - Single-call NSC transport (no polling, no shared-memory ring): client `Send` invokes the host-supplied veneer inline and caches the response; client `Recv` consumes the cached response on the first call (subsequent calls return `WH_ERROR_NOTREADY` until the next `Send`).
 - Server-side callbacks that consume the request the host's veneer parked in a static context and write the response back to the non-secure caller's buffer.
 
-The transport itself is target-agnostic; the STM32H5-specific glue (NSC veneer, `whFlashCb` flash adapter, secure-side server init, NS test exerciser) lives in the wolfBoot port.
+The transport is target-agnostic. Bringing it up on a new ARMv8-M part is a porting exercise on the host side only: provide the `cmse_nonsecure_entry` veneer that fronts `wcs_wolfhsm_transmit`, plus whatever flash/NVM adapter and server init the deployment needs.
 
 ### POSIX
 
diff --git a/port/armv8m-tz/wh_transport_nsc.c b/port/armv8m-tz/wh_transport_nsc.c
@@ -1,5 +1,5 @@
 /*
- * port/stmicro/stm32-tz/wh_transport_nsc.c
+ * port/armv8m-tz/wh_transport_nsc.c
  *
  * Copyright (C) 2026 wolfSSL Inc.
  *
@@ -16,13 +16,12 @@
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
+ * along with wolfHSM.  If not, see <http://www.gnu.org/licenses/>.
  */
 
 #include "wolfhsm/wh_settings.h"
 
-#ifdef WOLFHSM_CFG_PORT_STM32_TZ_NSC
+#ifdef WOLFHSM_CFG_PORT_ARMV8M_TZ_NSC
 
 #include <stdint.h>
 #include <string.h>
@@ -79,12 +78,21 @@ static int _NscClientSend(void* context, uint16_t size, const void* data)
     if (size == 0U || size > WH_TRANSPORT_NSC_BUFFER_SIZE) {
         return WH_ERROR_BADARGS;
     }
+    /* prior response must be consumed before next Send */
+    if (ctx->last_rsp_size != 0U) {
+        return WH_ERROR_NOTREADY;
+    }
 
     rspSz = (uint32_t)WH_TRANSPORT_NSC_BUFFER_SIZE;
     rc    = wcs_wolfhsm_transmit((const uint8_t*)data, (uint32_t)size,
                                  ctx->rsp_buf, &rspSz);
     if (rc != 0) {
         ctx->last_rsp_size = 0;
+        /* propagate known wolfHSM error codes, collapse unknowns */
+        if (rc == WH_ERROR_BADARGS || rc == WH_ERROR_NOTREADY ||
+            rc == WH_ERROR_ABORTED) {
+            return rc;
+        }
         return WH_ERROR_ABORTED;
     }
     if (rspSz == 0U || rspSz > (uint32_t)WH_TRANSPORT_NSC_BUFFER_SIZE) {
@@ -107,6 +115,10 @@ static int _NscClientRecv(void* context, uint16_t* out_size, void* data)
     if (ctx->last_rsp_size == 0U) {
         return WH_ERROR_NOTREADY;
     }
+    /* out_size is in/out capacity; reject truncation, keep cached response */
+    if (*out_size < ctx->last_rsp_size) {
+        return WH_ERROR_BADARGS;
+    }
 
     memcpy(data, ctx->rsp_buf, ctx->last_rsp_size);
     *out_size          = ctx->last_rsp_size;
@@ -170,15 +182,14 @@ static int _NscServerRecv(void* context, uint16_t* inout_size, void* data)
     if (!ctx->request_pending || ctx->req_buf == NULL || ctx->req_size == 0U) {
         return WH_ERROR_NOTREADY;
     }
+    /* clear stale rsp_size up-front so every exit path leaves a clean state */
+    ctx->rsp_size = 0;
+
     if (ctx->req_size > *inout_size) {
         ctx->request_pending = 0;
         return WH_ERROR_ABORTED;
     }
 
-    /* Stale value from the previous call must not leak through error paths
-     * that skip Send. */
-    ctx->rsp_size = 0;
-
     memcpy(data, ctx->req_buf, ctx->req_size);
     *inout_size          = ctx->req_size;
     ctx->request_pending = 0;
@@ -187,6 +198,7 @@ static int _NscServerRecv(void* context, uint16_t* inout_size, void* data)
 
 static int _NscServerSend(void* context, uint16_t size, const void* data)
 {
+    /* veneer is responsible for Recv/Send pairing; Send does not enforce it */
     whTransportNscServerContext* ctx = (whTransportNscServerContext*)context;
 
     if (ctx == NULL || data == NULL) {
@@ -210,6 +222,8 @@ static int _NscServerCleanup(void* context)
     if (ctx == NULL) {
         return WH_ERROR_BADARGS;
     }
+    /* clear stale NS pointers so they cannot survive reinit */
+    memset(ctx, 0, sizeof(*ctx));
     return WH_ERROR_OK;
 }
 
@@ -220,4 +234,4 @@ const whTransportServerCb whTransportNscServer_Cb = {
     .Cleanup = _NscServerCleanup,
 };
 
-#endif /* WOLFHSM_CFG_PORT_STM32_TZ_NSC */
+#endif /* WOLFHSM_CFG_PORT_ARMV8M_TZ_NSC */
diff --git a/port/armv8m-tz/wh_transport_nsc.h b/port/armv8m-tz/wh_transport_nsc.h
@@ -1,5 +1,5 @@
 /*
- * port/stmicro/stm32-tz/wh_transport_nsc.h
+ * port/armv8m-tz/wh_transport_nsc.h
  *
  * Copyright (C) 2026 wolfSSL Inc.
  *
@@ -16,8 +16,7 @@
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
+ * along with wolfHSM.  If not, see <http://www.gnu.org/licenses/>.
  */
 
 /*
@@ -31,16 +30,16 @@
  * notify counter, or async producer/consumer — Send delivers the
  * response, Recv just hands it back.
  *
- * The transport is generic to any ARMv8-M TrustZone target; the
- * STM32-specific dependencies live in the host (wolfBoot).
+ * The transport is target-agnostic across ARMv8-M TrustZone parts;
+ * the target-specific NSC veneer is provided by the host.
  */
 
 #ifndef WH_TRANSPORT_NSC_H_
 #define WH_TRANSPORT_NSC_H_
 
 #include "wolfhsm/wh_settings.h"
 
-#ifdef WOLFHSM_CFG_PORT_STM32_TZ_NSC
+#ifdef WOLFHSM_CFG_PORT_ARMV8M_TZ_NSC
 
 #include <stdint.h>
 #include "wolfhsm/wh_comm.h"
@@ -55,10 +54,10 @@ typedef struct {
     uint8_t  rsp_buf[WH_TRANSPORT_NSC_BUFFER_SIZE];
     uint16_t last_rsp_size;
     uint8_t  initialized;
-    uint8_t  WH_PAD[5]; /* Pad to 8-byte alignment */
+    uint8_t  WH_PAD[5]; /* trailing slack */
 } whTransportNscClientContext;
 
-/* Empty config struct - kept for ABI symmetry with other transports */
+/* Empty config; Init accepts NULL since there is nothing to read. */
 typedef struct {
     uint8_t WH_PAD[1];
 } whTransportNscClientConfig;
@@ -71,8 +70,8 @@ typedef struct {
  */
 typedef struct {
     const uint8_t* req_buf;
-    uint16_t       req_size;
     uint8_t*       rsp_buf;
+    uint16_t       req_size;
     uint16_t       rsp_capacity;
     uint16_t       rsp_size;        /* set by Send, read by veneer */
     uint8_t        request_pending; /* set by veneer, cleared by Recv */
@@ -83,9 +82,10 @@ typedef struct {
     uint8_t WH_PAD[1];
 } whTransportNscServerConfig;
 
+/* Pre-populated tables; callbacks are file-local in wh_transport_nsc.c */
 extern const whTransportClientCb whTransportNscClient_Cb;
 extern const whTransportServerCb whTransportNscServer_Cb;
 
-#endif /* WOLFHSM_CFG_PORT_STM32_TZ_NSC */
+#endif /* WOLFHSM_CFG_PORT_ARMV8M_TZ_NSC */
 
 #endif /* WH_TRANSPORT_NSC_H_ */
diff --git a/test/Makefile b/test/Makefile
@@ -165,12 +165,12 @@ ifeq ($(AUTH),1)
 	DEF += -DWOLFHSM_CFG_ENABLE_AUTHENTICATION
 endif
 
-# Build the STM32 TZ NSC bridge transport plus its host unit test
-ifeq ($(STM32_TZ_NSC),1)
-	DEF += -DWOLFHSM_CFG_PORT_STM32_TZ_NSC
-	WOLFHSM_STM32_TZ_DIR := $(WOLFHSM_DIR)/port/stmicro/stm32-tz
-	INC += -I$(WOLFHSM_STM32_TZ_DIR)
-	SRC_C += $(wildcard $(WOLFHSM_STM32_TZ_DIR)/*.c)
+# Build the ARMv8-M TrustZone NSC bridge transport plus its host unit test
+ifeq ($(ARMV8M_TZ_NSC),1)
+	DEF += -DWOLFHSM_CFG_PORT_ARMV8M_TZ_NSC
+	WOLFHSM_ARMV8M_TZ_DIR := $(WOLFHSM_DIR)/port/armv8m-tz
+	INC += -I$(WOLFHSM_ARMV8M_TZ_DIR)
+	SRC_C += $(wildcard $(WOLFHSM_ARMV8M_TZ_DIR)/*.c)
 endif
 
 ## Project defines
diff --git a/test/wh_test.c b/test/wh_test.c
@@ -46,7 +46,7 @@
 #include "wh_test_timeout.h"
 #include "wh_test_dma.h"
 #include "wh_test_keystore_reqsize.h"
-#ifdef WOLFHSM_CFG_PORT_STM32_TZ_NSC
+#ifdef WOLFHSM_CFG_PORT_ARMV8M_TZ_NSC
 #include "wh_test_transport_nsc.h"
 #endif
 #ifdef WOLFHSM_CFG_ENABLE_AUTHENTICATION
@@ -108,7 +108,7 @@ int whTest_Unit(void)
     WH_TEST_ASSERT(0 == whTest_Comm());
     WH_TEST_ASSERT(0 == whTest_ClientServer());
 
-#ifdef WOLFHSM_CFG_PORT_STM32_TZ_NSC
+#ifdef WOLFHSM_CFG_PORT_ARMV8M_TZ_NSC
     WH_TEST_ASSERT(0 == whTest_TransportNsc());
 #endif
 
diff --git a/test/wh_test_check_struct_padding.c b/test/wh_test_check_struct_padding.c
@@ -203,4 +203,10 @@ whMessageCert_VerifyAcertRequest whMessageCert_VerifyAcertRequest_test;
 #endif /* WOLFHSM_CFG_CERTIFICATE_MANAGER_ACERT */
 #endif /* WOLFHSM_CFG_CERTIFICATE_MANAGER */
 
+#ifdef WOLFHSM_CFG_PORT_ARMV8M_TZ_NSC
+#include "wh_transport_nsc.h"
+whTransportNscClientContext whTransportNscClientContext_test;
+whTransportNscServerContext whTransportNscServerContext_test;
+#endif /* WOLFHSM_CFG_PORT_ARMV8M_TZ_NSC */
+
 #endif /* WH_TEST_CHECK_STRUCT_PADDING_C_ */
diff --git a/test/wh_test_transport_nsc.c b/test/wh_test_transport_nsc.c
@@ -21,7 +21,7 @@
 
 #include "wolfhsm/wh_settings.h"
 
-#ifdef WOLFHSM_CFG_PORT_STM32_TZ_NSC
+#ifdef WOLFHSM_CFG_PORT_ARMV8M_TZ_NSC
 
 #include <stdint.h>
 #include <string.h>
@@ -100,11 +100,34 @@ static int test_client_callbacks(void)
     WH_TEST_ASSERT_RETURN(WH_ERROR_NOTREADY ==
         whTransportNscClient_Cb.Recv(&ctx, &sz, data_out));
 
+    /* too-small buffer returns BADARGS, cached response preserved */
+    rc = whTransportNscClient_Cb.Send(&ctx, sizeof(data_in), data_in);
+    WH_TEST_ASSERT_RETURN(rc == WH_ERROR_OK);
+    sz = (uint16_t)(sizeof(data_in));
+    WH_TEST_ASSERT_RETURN(WH_ERROR_BADARGS ==
+        whTransportNscClient_Cb.Recv(&ctx, &sz, data_out));
+    /* second Send before Recv consumes prior reply is NOTREADY */
+    WH_TEST_ASSERT_RETURN(WH_ERROR_NOTREADY ==
+        whTransportNscClient_Cb.Send(&ctx, sizeof(data_in), data_in));
+    sz = sizeof(data_out);
+    rc = whTransportNscClient_Cb.Recv(&ctx, &sz, data_out);
+    WH_TEST_ASSERT_RETURN(rc == WH_ERROR_OK);
+    WH_TEST_ASSERT_RETURN(sz == sizeof(data_in) + 1U);
+
     g_stub_force_rc = -42;
     rc = whTransportNscClient_Cb.Send(&ctx, sizeof(data_in), data_in);
     WH_TEST_ASSERT_RETURN(rc == WH_ERROR_ABORTED);
     g_stub_force_rc = 0;
 
+    /* WH_ERROR_* return values from the veneer are propagated unchanged. */
+    g_stub_force_rc = WH_ERROR_BADARGS;
+    rc = whTransportNscClient_Cb.Send(&ctx, sizeof(data_in), data_in);
+    WH_TEST_ASSERT_RETURN(rc == WH_ERROR_BADARGS);
+    g_stub_force_rc = WH_ERROR_NOTREADY;
+    rc = whTransportNscClient_Cb.Send(&ctx, sizeof(data_in), data_in);
+    WH_TEST_ASSERT_RETURN(rc == WH_ERROR_NOTREADY);
+    g_stub_force_rc = 0;
+
     g_stub_force_rspSz = (uint32_t)WH_TRANSPORT_NSC_BUFFER_SIZE + 1U;
     rc                 = whTransportNscClient_Cb.Send(&ctx, sizeof(data_in),
                                                       data_in);
@@ -157,11 +180,12 @@ static int test_server_callbacks(void)
     ctx.rsp_size        = 0xBEEF;
     ctx.request_pending = 1;
 
-    /* Oversize: must clear request_pending. */
+    /* oversize must clear request_pending and rsp_size */
     sz = (uint16_t)(sizeof(req) - 1U);
     rc = whTransportNscServer_Cb.Recv(&ctx, &sz, data_buf);
     WH_TEST_ASSERT_RETURN(rc == WH_ERROR_ABORTED);
     WH_TEST_ASSERT_RETURN(ctx.request_pending == 0U);
+    WH_TEST_ASSERT_RETURN(ctx.rsp_size == 0U);
 
     ctx.req_buf         = req;
     ctx.req_size        = (uint16_t)sizeof(req);
@@ -209,4 +233,4 @@ int whTest_TransportNsc(void)
     return WH_TEST_SUCCESS;
 }
 
-#endif /* WOLFHSM_CFG_PORT_STM32_TZ_NSC */
+#endif /* WOLFHSM_CFG_PORT_ARMV8M_TZ_NSC */
diff --git a/wolfhsm/wh_settings.h b/wolfhsm/wh_settings.h
@@ -129,6 +129,14 @@
  *  WOLFHSM_CFG_PORT_GETTIME - Function-like macro returning the current system
  *      time in microseconds as a uint64_t. Must be defined in wolfhsm_cfg.h for
  *      the active port UNLESS WOLFHSM_CFG_NO_SYS_TIME is defined
+ *
+ *  WOLFHSM_CFG_PORT_ARMV8M_TZ_NSC - If defined, build the ARMv8-M TrustZone
+ *      non-secure-callable (NSC) bridge transport in
+ *      port/armv8m-tz/wh_transport_nsc.{c,h}. Target-agnostic across
+ *      ARMv8-M Cortex-M parts; the non-secure client calls into the
+ *      secure-side server through a single cmse_nonsecure_entry veneer
+ *      provided by the host (e.g. wolfBoot's WOLFCRYPT_TZ_WOLFHSM engine).
+ *      Default: Not defined
 
  *  Overridable porting functions:
  *
