Add CRC integrity check to NVM flash state

[bigbrett]

Adds optional CRC16 integrity checking to the nvm_flash backend’s on-flash object state so the directory load, full-object reads, and compaction copies can detect corruption (gated by WOLFHSM_CFG_NVM_FLASH_CRC16), and wires this option through tests, tooling, docs, and CI.

Changes:

• Add wh_Utils_Crc16() utility plus WH_UTILS_CRC16_INIT seed constant.
• Extend nvm_flash on-flash format to embed CRC16 values in object start/count state words and verify metadata/data at key read/copy points.
• Add CRC-enabled test coverage and build knobs for test, test-refactor, and whnvmtool, including CI jobs.

[Copilot]

Pull request overview

Adds optional CRC16 (CRC-16/CCITT-FALSE) integrity checking to the nvm_flash backend’s on-flash object state so the directory load, full-object reads, and compaction copies can detect corruption (gated by WOLFHSM_CFG_NVM_FLASH_CRC16), and wires this option through tests, tooling, docs, and CI.

Changes:

• Add wh_Utils_Crc16() utility plus WH_UTILS_CRC16_INIT seed constant.
• Extend nvm_flash on-flash format to embed CRC16 values in object start/count state words and verify metadata/data at key read/copy points.
• Add CRC-enabled test coverage and build knobs for test, test-refactor, and whnvmtool, including CI jobs.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
wolfhsm/wh_utils.h	Declares CRC16 API and seed constant.
src/wh_utils.c	Implements CRC-16/CCITT-FALSE routine used by NVM flash CRC feature.
wolfhsm/wh_settings.h	Documents WOLFHSM_CFG_NVM_FLASH_CRC16 configuration macro and format incompatibility.
wolfhsm/wh_nvm_flash.h	Extends NVM flash in-memory state with CRC fields and adds NF_STATUS_CRC_BAD.
src/wh_nvm_flash.c	Stores CRCs in state words, verifies metadata/data, and updates directory parsing/accounting for CRC failures.
tools/whnvmtool/Makefile	Adds NVM_FLASH_CRC=1 build switch to compile tool with CRC-enabled format.
tools/whnvmtool/test/Makefile	Adds CRC build switch for whnvmtool tests.
tools/whnvmtool/README.md	Documents CRC format compatibility requirement between tool and server.
test/Makefile	Adds NVM_FLASH_CRC=1 build switch for CRC-enabled test runs.
test/wh_test_nvm_flash.h	Declares CRC16 integrity test entry point (guarded by macro).
test/wh_test_nvm_flash.c	Adds runtime tests for CRC vectors and corruption detection/handling in NVM flash backend.
test-refactor/README.md	Updates test mapping documentation to include CRC test coverage.
test-refactor/posix/Makefile	Adds NVM_FLASH_CRC=1 build switch for refactor POSIX test runs.
test-refactor/posix/wh_test_posix_main.c	Runs the refactor CRC test in the POSIX harness.
test-refactor/posix/wh_test_nvm_flash.c	Adds refactor CRC16 integrity test implementation.
docs/src/9-Configuration.md	Documents the new CRC config macro in the configuration reference.
docs/src/6-Utilities.md	Updates whnvmtool compatibility requirements to include CRC setting.
docs/src/5-Features.md	Documents CRC behavior/caveats for nvm_flash backend.
.github/workflows/build-and-test.yml	Adds CI job for CRC-enabled test build/run.
.github/workflows/build-and-test-whnvmtool.yml	Adds CI job for CRC-enabled whnvmtool build/tests.
.github/workflows/build-and-test-refactor.yml	Adds CI job for CRC-enabled refactor test build/run.

Suppressed comments (1)

src/wh_nvm_flash.c:295

• The metadata CRC verification currently runs for both NF_STATUS_USED and NF_STATUS_DATA_BAD entries. For NF_STATUS_DATA_BAD (count word blank), failing the metadata CRC changes the status to NF_STATUS_CRC_BAD, but the directory parser assumes CRC_BAD entries have a valid state.count from the count word. This can mis-account reserved space (and can become undefined behavior if count was never set). Only apply the metadata CRC check when the object state is fully present (NF_STATUS_USED).

#ifdef WOLFHSM_CFG_NVM_FLASH_CRC16
            /* Verify the metadata against the CRC in the start state word */
            if (wh_Utils_Crc16(WH_UTILS_CRC16_INIT, &object->metadata,
                               sizeof(object->metadata)) !=
                object->state.crc_meta) {
                object->state.status = NF_STATUS_CRC_BAD;
                clear_metadata       = 1;
            }
#endif

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[wolfSSL-Fenrir-bot]

Fenrir Automated Review — PR #503

Scan targets checked: wolfhsm-core-bugs, wolfhsm-crypto-bugs, wolfhsm-src

Findings: 1
1 finding(s) posted as inline comments (see file-level comments below)

This review was generated automatically by Fenrir. Findings are non-blocking.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.

[wolfSSL-Fenrir-bot]

Fenrir Automated Review — PR #503

Scan targets checked: wolfhsm-core-bugs, wolfhsm-crypto-bugs, wolfhsm-src
Findings: 2
1 finding(s) posted as inline comments (see file-level comments below)

Low (1)

CRC-corrupted metadata resurrects superseded object version

File: src/wh_nvm_flash.c:927
Function: nfMemDirectory_Parse
Category: NV storage vulnerabilities

The duplicate-id reclaim loop only demotes an older NF_STATUS_USED entry when the newest same-id entry is also NF_STATUS_USED. If the newest entry is NF_STATUS_CRC_BAD (metadata failed CRC), the older entry is never marked bad and nfMemDirectory_FindObjectIndexById returns it, silently making a superseded object (e.g. a rotated key or cert) authoritative again.

Recommendation: Also treat NF_STATUS_CRC_BAD (and NF_STATUS_DATA_BAD) newest entries as superseding-but-invalid so older same-id entries stay reclaimed, or track ids independent of the newest entry's verification status.

Referenced code: src/wh_nvm_flash.c:927-931 (5 lines)

---

This review was generated automatically by Fenrir. Findings are non-blocking.

[wolfSSL-Fenrir-bot]

Fenrir Automated Review — PR #503

Scan targets checked: wolfhsm-core-bugs, wolfhsm-crypto-bugs, wolfhsm-src

Findings: 1
1 finding(s) posted as inline comments (see file-level comments below)

This review was generated automatically by Fenrir. Findings are non-blocking.

[billphipps]

Looks great! Can you modify the memDirectory per comments?

[billphipps]

Thank you ! This looks great!