Add CRC integrity check to NVM flash state

.github/workflows/build-and-test-refactor.yml

@@ -66,6 +66,10 @@ jobs:
     - name: Build and test refactor DMA ASAN
       run: cd test-refactor/posix && make clean && make -j DMA=1 ASAN=1 WOLFSSL_DIR=../../wolfssl && make run
 
+    # Build and test with NVM flash CRC16 integrity checking enabled
+    - name: Build and test refactor NVM flash CRC ASAN
+      run: cd test-refactor/posix && make clean && make -j NVM_FLASH_CRC=1 ASAN=1 WOLFSSL_DIR=../../wolfssl && make run
+
     # Build and test with LMS and XMSS both in verify-only mode
     - name: Build and test refactor DMA ASAN LMS/XMSS verify-only
       run: cd test-refactor/posix && make clean && make -j DMA=1 ASAN=1 LMS_VERIFY_ONLY=1 XMSS_VERIFY_ONLY=1 WOLFSSL_DIR=../../wolfssl && make run

.github/workflows/build-and-test-whnvmtool.yml

@@ -57,6 +57,9 @@ jobs:
     - name: Build and test NVM tool with ASAN
       run: cd tools/whnvmtool && make clean && make check WOLFSSL_DIR=../../wolfssl ASAN=1
 
+    - name: Build and test NVM tool with NVM flash CRC ASAN
+      run: cd tools/whnvmtool && make clean && make check WOLFSSL_DIR=../../wolfssl NVM_FLASH_CRC=1 ASAN=1
+
     # Build and test with DEBUG=1
     - name: Build and test NVM tool with DEBUG
       run: cd tools/whnvmtool && make clean && make check WOLFSSL_DIR=../../wolfssl DEBUG=1

.github/workflows/build-and-test.yml

@@ -66,6 +66,10 @@ jobs:
     - name: Build and test DMA ASAN
       run: cd test && make clean && make -j DMA=1 ASAN=1 WOLFSSL_DIR=../wolfssl && make run
 
+    # Build and test with NVM flash CRC16 integrity checking enabled
+    - name: Build and test NVM flash CRC ASAN
+      run: cd test && make clean && make -j NVM_FLASH_CRC=1 ASAN=1 WOLFSSL_DIR=../wolfssl && make run
+
     # Build and test with LMS and XMSS both in verify-only mode
     - name: Build and test DMA ASAN LMS/XMSS verify-only
       run: cd test && make clean && make -j DMA=1 ASAN=1 LMS_VERIFY_ONLY=1 XMSS_VERIFY_ONLY=1 WOLFSSL_DIR=../wolfssl && make run

docs/src/5-Features.md

@@ -225,6 +225,8 @@ The access field is used to express coarser-grained permissions (owner / other /
 The `wh_Nvm_*` API is implemented against a backend callback table (`whNvmCb`) that abstracts the details of how objects are actually laid out on storage. The core library does not depend on any particular backend — selecting a backend is part of server configuration, and ports or applications can supply their own implementations against the same interface. wolfHSM ships with two reference backends, both built on top of the [flash abstraction](#flash-abstraction):
 
 - **`nvm_flash`** (`wh_nvm_flash.c`): the default backend, suitable for flash devices with small write granularity (8 bytes or less). It manages two equal-sized partitions in flash, with one designated as active at any time. New objects are added by programming directly into free space at the end of the active partition, which keeps write amplification low for read-heavy and append-dominated workloads. A directory of object state is cached in RAM and rebuilt from flash at initialization. Destruction of objects (and explicit compaction) is performed by regenerating the inactive partition with only the surviving objects, then atomically switching the active partition pointer and erasing the old one. An interruption before the switch leaves the previous partition intact; an interruption after the switch is recovered by completing the erase of the now-inactive partition on the next boot.
+
+    With `WOLFHSM_CFG_NVM_FLASH_CRC16` defined, `nvm_flash` additionally stores a CRC16 (CRC-16/CCITT-FALSE) of each object's metadata and data in spare bits of the on-flash object state, providing integrity checking against flash corruption. Metadata is verified whenever the directory is rebuilt from flash: an object whose metadata fails its CRC is treated as absent and reclaimable, and the next compaction drops it and frees its slot and data. For an interrupted (uncommitted) write whose metadata fails its CRC, the extent of the partially written data is unknown, so the remainder of the data area is reserved and new writes return `WH_ERROR_NOSPACE` until a compaction reclaims the entry (`wh_Nvm_AddObjectWithReclaim` does this automatically). Object data is verified on full-object reads (offset 0 for the object's full length) and while objects are copied during compaction, returning `WH_ERROR_NOTVERIFIED` on mismatch — a failed compaction copy aborts the reclaim with the active partition intact. Reads of a partial byte range are *not* verified, which includes client reads issued at a nonzero offset or chunked through a communication buffer smaller than the object; server-local consumers (keystore, certificate manager, image manager) read whole objects and are always verified. Two caveats: if an object was overwritten and the newest copy's metadata is corrupted before the duplicate is compacted away, the previous version becomes visible again until the next compaction; and enabling the option changes the on-flash format, so images written with and without it are mutually incompatible (existing images must be re-provisioned, and `whnvmtool` must be built with the same setting).
 - **`nvm_flash_log`** (`wh_nvm_flash_log.c`): an alternative backend designed for flash devices with **large write granularity** (e.g. 64 bytes) where every program operation must be aligned and padded to that boundary. It also uses a two-partition layout, but caches the entire active partition in RAM and rewrites the whole inactive partition on every mutation. Each partition header carries a monotonic epoch counter, and the partition with the highest epoch is treated as authoritative on the next initialization. The implementation favors simplicity and a uniform write pattern at the cost of higher write amplification, which is acceptable on the read-heavy workloads it is intended for. Selected at build time via `WOLFHSM_CFG_SERVER_NVM_FLASH_LOG`.
 
 Both backends bind to a `whFlashCb` flash driver supplied by the port; the choice between them is a function of the underlying flash device's program granularity and the application's write profile, not of any user-facing feature. Ports targeting microcontrollers with conventional NOR flash typically use `nvm_flash`; ports targeting devices whose program operation is fundamentally a 32- or 64-byte page write are better served by `nvm_flash_log`.

docs/src/6-Utilities.md

@@ -18,7 +18,7 @@ This chapter describes the auxiliary tools that ship alongside the wolfHSM clien
 
 The NVM provisioning tool (`tools/whnvmtool/`) is a host-side utility that builds a pre-populated wolfHSM NVM image from a configuration file. It is intended for device provisioning: rather than having the server populate its NVM at runtime, the integrator describes the desired initial contents — a set of NVM objects and keys, each with its metadata ID, access permissions, flags, label, and a path to the binary payload — and the tool produces a single image file that can be programmed into the device's flash at manufacture or used in place to back a `whNvmFlash` provider in simulation. Currently the tool targets the `whNvmFlash` provider; the generated image is binary, and can be converted to Intel HEX with the standard `objcopy` workflow for use with automated programmers.
 
-Because the on-flash layout depends on build-time configuration, the tool must be compiled against the same wolfHSM version as the target server and with a matching `WOLFHSM_CFG_NVM_OBJECT_COUNT`, and the `--size` argument must match the server's `whNvmFlash` partition size. For the full configuration file schema, command-line options, hex conversion recipe, and test workflow, see [`tools/whnvmtool/README.md`](https://github.com/wolfSSL/wolfHSM/blob/main/tools/whnvmtool/README.md).
+Because the on-flash layout depends on build-time configuration, the tool must be compiled against the same wolfHSM version as the target server and with a matching `WOLFHSM_CFG_NVM_OBJECT_COUNT` and `WOLFHSM_CFG_NVM_FLASH_CRC16` setting, and the `--size` argument must match the server's `whNvmFlash` partition size. For the full configuration file schema, command-line options, hex conversion recipe, and test workflow, see [`tools/whnvmtool/README.md`](https://github.com/wolfSSL/wolfHSM/blob/main/tools/whnvmtool/README.md).
 
 ## Benchmark Suite
 

docs/src/9-Configuration.md

@@ -98,6 +98,7 @@ These macros size the server-side key cache. The cache is split into "regular" s
 | Macro | Default | Description |
 |---|---|---|
 | `WOLFHSM_CFG_NVM_OBJECT_COUNT` | `32` | Maximum number of objects the NVM directory can hold simultaneously (RAM directory cache *and* the on-disk directory it mirrors). Determines the upper bound on the number of keys, certificates, counters, and user objects that can coexist in NVM at one time. |
+| `WOLFHSM_CFG_NVM_FLASH_CRC16` | Undefined | If defined, the `nvm_flash` backend stores a CRC16 of each object's metadata and data in the on-flash object state and verifies them: metadata when the directory is loaded (failing objects become invisible and reclaimable), data on full-object reads and reclaim copies (returning `WH_ERROR_NOTVERIFIED` on mismatch). Partial reads are not verified. Changes the on-flash format: images written with and without this option are mutually incompatible, and `whnvmtool` must be built with the same setting as the server. |
 | `WOLFHSM_CFG_SERVER_NVM_FLASH_LOG` | Undefined | If defined, compile the log-structured NVM flash backend (`wh_nvm_flash_log`). When enabled it can be selected at runtime as an alternative to the regular flash backend; useful for flash parts that tolerate fewer erases or that prefer append-only update patterns. |
 
 ## Certificate Manager