fwTPM: append-only NV journal for write-once flash ports and swtpm UART symlink support

Author: dgarske

CMakeLists.txt

@@ -39,6 +39,10 @@ set(WOLFTPM_FWTPM_FUZZ "no" CACHE STRING
     "Enable fwTPM fuzz target (requires libFuzzer, default: disabled)")
 set_property(CACHE WOLFTPM_FWTPM_FUZZ
     PROPERTY STRINGS "yes;no")
+set(WOLFTPM_FWTPM_NV_APPEND_ONLY "no" CACHE STRING
+    "Enable append-only NV journal for write-once flash fwTPM ports (default: disabled)")
+set_property(CACHE WOLFTPM_FWTPM_NV_APPEND_ONLY
+    PROPERTY STRINGS "yes;no")
 
 # fwtpm-only forces fwtpm on
 if(WOLFTPM_FWTPM_ONLY)
@@ -523,6 +527,9 @@ if(WOLFTPM_FWTPM)
     if(WOLFTPM_FWTPM_TIS)
         target_compile_definitions(fwtpm_server PRIVATE "WOLFTPM_FWTPM_TIS")
     endif()
+    if(WOLFTPM_FWTPM_NV_APPEND_ONLY)
+        target_compile_definitions(fwtpm_server PRIVATE "WOLFTPM_FWTPM_NV_APPEND_ONLY")
+    endif()
     target_link_libraries(fwtpm_server PRIVATE wolftpm_wolfssl_dep)
     target_include_directories(fwtpm_server PRIVATE
         ${CMAKE_CURRENT_SOURCE_DIR}
@@ -546,6 +553,9 @@ if(WOLFTPM_FWTPM)
         "WOLFTPM_FWTPM"
         "FWTPM_NV_FILE=\"fwtpm_test_nv.bin\""
     )
+    if(WOLFTPM_FWTPM_NV_APPEND_ONLY)
+        target_compile_definitions(fwtpm_unit_test PRIVATE "WOLFTPM_FWTPM_NV_APPEND_ONLY")
+    endif()
     target_link_libraries(fwtpm_unit_test PRIVATE wolftpm_wolfssl_dep)
     target_include_directories(fwtpm_unit_test PRIVATE
         ${CMAKE_CURRENT_SOURCE_DIR}
@@ -562,6 +572,9 @@ if(WOLFTPM_FWTPM)
             ${FWTPM_CORE_SOURCES}
         )
         target_compile_definitions(fwtpm_fuzz PRIVATE "WOLFTPM_FWTPM")
+        if(WOLFTPM_FWTPM_NV_APPEND_ONLY)
+            target_compile_definitions(fwtpm_fuzz PRIVATE "WOLFTPM_FWTPM_NV_APPEND_ONLY")
+        endif()
         target_link_libraries(fwtpm_fuzz PRIVATE wolftpm_wolfssl_dep)
         target_include_directories(fwtpm_fuzz PRIVATE
             ${CMAKE_CURRENT_SOURCE_DIR}

configure.ac

@@ -415,6 +415,17 @@ then
     fi
 fi
 
+# Append-only NV journal for write-once flash fwTPM ports (opt-in)
+AC_ARG_ENABLE([fwtpm-nv-appendonly],
+    [AS_HELP_STRING([--enable-fwtpm-nv-appendonly],[Enable the append-only NV journal mode for write-once flash fwTPM ports (default: disabled)])],
+    [ ENABLED_FWTPM_NV_APPENDONLY=$enableval ],
+    [ ENABLED_FWTPM_NV_APPENDONLY=no ]
+    )
+if test "x$ENABLED_FWTPM_NV_APPENDONLY" = "xyes"
+then
+    AM_CFLAGS="$AM_CFLAGS -DWOLFTPM_FWTPM_NV_APPEND_ONLY"
+fi
+
 # Fuzz target
 AC_ARG_ENABLE([fuzz],
     [AS_HELP_STRING([--enable-fuzz],[Enable fuzz targets (default: disabled)])],

docs/FWTPM.md

@@ -43,7 +43,7 @@ fwTPM can replace a hardware TPM for:
 |------|------|
 | `fwtpm_command.c` | TPM 2.0 command processor and dispatch table (~9500 lines) |
 | `fwtpm_io.c` | Transport layer -- SWTPM TCP socket protocol (default) |
-| `fwtpm_nv.c` | NV storage -- file-based (default), HAL-abstracted for embedded |
+| `fwtpm_nv.c` | NV storage -- file-based (default); HAL-abstracted, with a built-in append-only mode for write-once flash |
 | `fwtpm_tis.c` | TIS register state machine (transport-agnostic) |
 | `fwtpm_tis_shm.c` | POSIX shared memory + semaphore TIS transport |
 | `fwtpm_main.c` | Server entry point, CLI argument parsing |
@@ -120,6 +120,7 @@ make
 | `--enable-fwtpm` | Build `fwtpm_server` binary (alongside client library) |
 | `--enable-fwtpm-only` | Build only `fwtpm_server` (no client library, examples, or tests) |
 | `--enable-swtpm` | Use SWTPM TCP socket transport (ports 2321/2322) |
+| `--enable-fwtpm-nv-appendonly` | Append-only NV journal for write-once flash ports (off by default) |
 | `--enable-debug` | Enable debug logging |
 
 | Compile Define | Set By |
@@ -129,6 +130,7 @@ make
 | `WOLFTPM_FWTPM_HAL` | `--enable-fwtpm` without `--enable-swtpm` |
 | `WOLFTPM_FWTPM_TIS` | `--enable-fwtpm` without `--enable-swtpm` |
 | `WOLFTPM_ADV_IO` | Set with `WOLFTPM_FWTPM_HAL` |
+| `WOLFTPM_FWTPM_NV_APPEND_ONLY` | `--enable-fwtpm-nv-appendonly` (CMake `WOLFTPM_FWTPM_NV_APPEND_ONLY=yes`) |
 
 
 ## Usage
@@ -190,6 +192,51 @@ NV indices) in `fwtpm_nv.bin` (configurable via `FWTPM_NV_FILE`). On first
 start, seeds are randomly generated and saved. Subsequent starts reload
 existing state.
 
+#### NV Storage HAL (embedded ports)
+
+NV access is abstracted behind `FWTPM_NV_HAL` (`read`/`write`/`erase`/`ctx`/
+`maxSize`/`get_integrity_key`). The default backend is the file above; an
+embedded port supplies its own HAL and registers it before `FWTPM_Init()`.
+
+The journal is log-structured. On a byte-addressable backend (the file
+default) it writes TLV entries at byte-granular offsets, rewrites the header in
+place, and rewrites a trailing integrity MAC after every append. Internal flash
+and NOR are write-once and program-granularity aligned, so they cannot service
+in-place rewrites. Build with `--enable-fwtpm-nv-appendonly`
+(`-DWOLFTPM_FWTPM_NV_APPEND_ONLY`) and set `appendOnly` and `writeAlign` on the
+HAL; the journal then runs in append-only mode: the header is written only at
+compaction, `writePos` is derived by scanning on load, and each commit is
+sealed with an appended MAC-checkpoint entry padded up to `writeAlign`. The
+existing `read`/`write`/`erase` HAL is the integration point - no separate
+adapter.
+
+```c
+/* Native flash HAL. In append-only mode the journal only ever calls write()
+ * with writeAlign-aligned, forward, into-erased bytes, so write() is a simple
+ * flash program; erase() erases the region (sector loop); read() reads raw. */
+FWTPM_NV_HAL hal;
+XMEMSET(&hal, 0, sizeof(hal));
+hal.read = myRead; hal.write = myProgram; hal.erase = myErase;
+hal.ctx = myCtx; hal.maxSize = NV_SIZE;
+hal.appendOnly = 1;
+hal.writeAlign = PROG_SIZE;            /* flash word size, e.g. 16 (STM32H5) */
+hal.get_integrity_key = myDeviceSecret;/* recommended on flash */
+FWTPM_NV_SetHAL(&ctx, &hal);           /* before FWTPM_Init() */
+```
+
+In append-only mode the journal buffers a pending program granule internally and
+flushes full, aligned granules through `write()`, so a programmed cell is never
+rewritten and a whole sector is erased only on compaction. The header sector is
+therefore not erased on every append, and a torn final commit (e.g. on power
+loss) is ignored on the next load while all previously committed state survives.
+A `get_integrity_key` callback is strongly recommended on flash so the MAC
+checkpoints authenticate the journal and reject a torn or tampered tail.
+`writeAlign <= 1` selects no buffering, so byte-writable NV (EEPROM/FRAM) works
+with a plain `write()`. Compaction still erases the whole region before
+rewriting, so a power loss during compaction itself remains a vulnerable window
+(a future two-region ping-pong layout would close it). See
+`src/fwtpm/ports/README.md` for the full porting guide.
+
 
 ## Supported TPM 2.0 Commands