fwTPM: document lockoutAuth recovery as post-boot uptime and platform escape hatch per review

Author: aidangarske

docs/FWTPM.md

@@ -328,8 +328,16 @@ non-orderly shutdown adds a one-try penalty; on clockless builds neither applies
 power-off cannot accumulate into lockout. A failed `lockoutAuth` locks the
 lockout hierarchy: that lock persists across reboot and clears after
 `lockoutRecovery` seconds, except when `lockoutRecovery` is 0 (reboot-only
-recovery). `Startup`/`Shutdown` are never DA-gated, so a reboot in lockout can
-always recover. Entities marked `noDA` (`TPMA_OBJECT_noDA` on objects,
+recovery). Because the clock HAL reports milliseconds *since boot*, this timer
+measures continuous post-boot uptime, not wall-clock time across reboots — a
+device that reboots more often than `lockoutRecovery` extends its effective
+recovery window. The lock only blocks commands authorized via `lockoutAuth`
+(`DictionaryAttackLockReset`, `DictionaryAttackParameters`, lockout-authorized
+`Clear`); the platform hierarchy is always an escape hatch —
+`TPM2_ClearControl(platformAuth, clearDisable=NO)` then `TPM2_Clear(platformAuth)`
+recovers even when `disableClear` was set. `Startup`/`Shutdown` are never
+DA-gated, so a reboot in lockout can always recover. Entities marked `noDA`
+(`TPMA_OBJECT_noDA` on objects,
 `TPMA_NV_NO_DA` on NV indices) never feed the counter and stay usable during
 lockout. `TPM2_GetCapability(TPM_CAP_TPM_PROPERTIES)` reports
 `TPM_PT_MAX_AUTH_FAIL`, `TPM_PT_LOCKOUT_INTERVAL`, `TPM_PT_LOCKOUT_RECOVERY`,

src/fwtpm/fwtpm_command.c

@@ -696,7 +696,9 @@ static TPM_RC FwCmd_Startup(FWTPM_CTX* ctx, TPM2_Packet* cmd, int cmdSize,
          * is 0, or when there is no clock HAL to time-heal it (clockless
          * targets must keep a reboot recovery path). Otherwise it persists and
          * recovers on the timer, so a power-cycle cannot brute-force
-         * lockoutAuth. */
+         * lockoutAuth. The clock HAL is ms-since-boot, so re-seeding the heal
+         * baseline below measures recovery as continuous post-boot uptime; a
+         * power-cycle restarts the window rather than clearing the lock. */
         if (ctx->daLockoutRecovery == 0 || ctx->clockHal.get_ms == NULL) {
             ctx->lockoutAuthFailed = 0;
         }