Add LockdownAuth and LockdownStatus messages for hardened firmware builds

niccellular · niccellular · commit ae5ccf5acead · 2026-05-07T15:22:41.000-04:00
Companion proto changes for meshtastic/firmware#10349 (MESHTASTIC_LOCKDOWN hardened build option). Replaces a previous "no schema change" hack that repurposed SecurityConfig.private_key as the passphrase byte transport. AdminMessage.lockdown_auth (= 104): LockdownAuth carries a passphrase plus optional boots/until-epoch overrides, and a lock_now sentinel. Used for first-time provisioning, unlock on subsequent reboots, re-verification on already-unlocked devices, and Lock Now. Firmware decides between provision and unlock based on its own state. FromRadio.lockdown_status (= 18): LockdownStatus reports lockdown state to the client (NEEDS_PROVISION / LOCKED / UNLOCKED / UNLOCK_FAILED) plus structured fields for lock reason, token TTL, and unlock-failure backoff. Sent post-config and in response to each LockdownAuth command. Replaces the earlier scheme of encoding state as magic-string prefixes inside ClientNotification. Both messages are documented inline. No existing fields are altered.
diff --git a/meshtastic/admin.options b/meshtastic/admin.options
@@ -19,3 +19,5 @@
 *HamParameters.call_sign max_size:8
 *HamParameters.short_name max_size:5
 *NodeRemoteHardwarePinsResponse.node_remote_hardware_pins max_count:16
+
+*LockdownAuth.passphrase max_size:32
diff --git a/meshtastic/admin.proto b/meshtastic/admin.proto
@@ -521,9 +521,68 @@ message AdminMessage {
      * Parameters and sensor configuration
      */
     SensorConfig sensor_config = 103;
+
+    /*
+     * Lockdown passphrase delivery / unlock / lock-now command for hardened
+     * firmware builds (see MESHTASTIC_LOCKDOWN). Used to provision the
+     * passphrase on first boot, unlock encrypted storage on subsequent
+     * reboots, re-verify on already-unlocked devices to authorize a new
+     * client connection, or immediately re-lock the device.
+     *
+     * Replaces the earlier scheme that repurposed SecurityConfig.private_key
+     * to carry passphrase bytes; that hack is retired.
+     */
+    LockdownAuth lockdown_auth = 104;
   }
 }
 
+/*
+ * Lockdown passphrase delivery payload.
+ *
+ * One message handles three operations distinguished by content:
+ *   - Provision (first-time): passphrase set, lock_now=false. Firmware
+ *     generates DEK, wraps with passphrase-derived KEK, persists.
+ *   - Unlock: passphrase set, lock_now=false. Firmware verifies
+ *     passphrase against stored DEK, unlocks storage, authorizes the
+ *     connection that delivered this packet.
+ *   - Lock now: lock_now=true, passphrase ignored. Firmware revokes
+ *     all client auth and reboots into the locked state.
+ *
+ * Firmware decides between provision and unlock based on its own state
+ * (whether a DEK file already exists). Clients do not need to track
+ * which case applies.
+ */
+message LockdownAuth {
+  /*
+   * Passphrase bytes (1-32). Empty when lock_now is true.
+   * Capped to 32 to match the proto cap on related security fields.
+   */
+  bytes passphrase = 1;
+
+  /*
+   * Optional override of the boot-count token TTL granted on success.
+   * 0 = use firmware default (TOKEN_DEFAULT_BOOTS).
+   * On reboot the firmware decrements this; when it reaches 0 the
+   * device boots fully locked and requires a fresh passphrase.
+   */
+  uint32 boots_remaining = 2;
+
+  /*
+   * Optional wall-clock expiry for the unlock token, as absolute
+   * Unix-epoch seconds. 0 = no time limit (only the boot-count TTL
+   * applies). On boot, if the device RTC is set and now > this value,
+   * the token is treated as expired.
+   */
+  uint32 valid_until_epoch = 3;
+
+  /*
+   * If true, ignore passphrase fields, immediately revoke all
+   * connection-level admin authorization, and reboot the device into
+   * the locked state. Always honoured regardless of current lock state.
+   */
+  bool lock_now = 4;
+}
+
 /*
  * Firmware update mode for OTA updates
  */
diff --git a/meshtastic/mesh.options b/meshtastic/mesh.options
@@ -98,3 +98,7 @@
 *ChunkedPayload.chunk_count int_size:16
 *ChunkedPayload.chunk_index int_size:16
 *ChunkedPayload.payload_chunk max_size:228
+
+# Longest documented value is "token_wrong_size" (16 chars); 32 leaves room
+# for future short reasons without forcing nanopb to use callbacks.
+*LockdownStatus.lock_reason max_size:32
diff --git a/meshtastic/mesh.proto b/meshtastic/mesh.proto
@@ -2263,9 +2263,95 @@ message FromRadio {
      * Persistent data for device-ui
      */
     DeviceUIConfig deviceuiConfig = 17;
+
+    /*
+     * Lockdown state notification for hardened firmware builds.
+     * Sent post-config (so unauthorized clients learn they must
+     * provision/unlock) and after each LockdownAuth admin command
+     * to report success or failure. Replaces the earlier scheme of
+     * encoding state as magic-string prefixes inside ClientNotification.
+     */
+    LockdownStatus lockdown_status = 18;
   }
 }
 
+/*
+ * Lockdown state report from firmware to client (for hardened builds
+ * with MESHTASTIC_LOCKDOWN). Sent immediately after config_complete_id
+ * to inform a freshly-connected unauthorized client what it must do,
+ * and again in response to each LockdownAuth admin command.
+ */
+message LockdownStatus {
+  enum State {
+    /* Default; should not be sent. */
+    STATE_UNSPECIFIED = 0;
+
+    /*
+     * No passphrase has ever been provisioned on this device.
+     * Client should prompt the operator to set one.
+     */
+    NEEDS_PROVISION = 1;
+
+    /*
+     * Storage is locked or this client has not authenticated yet.
+     * lock_reason carries a machine-readable detail string.
+     * Client should present (or auto-replay) a passphrase via
+     * AdminMessage.lockdown_auth.
+     */
+    LOCKED = 2;
+
+    /*
+     * Passphrase accepted; client is now authorized for this connection.
+     * boots_remaining and valid_until_epoch describe the active session
+     * token's TTL.
+     */
+    UNLOCKED = 3;
+
+    /*
+     * Passphrase rejected. backoff_seconds is non-zero when rate-limited.
+     */
+    UNLOCK_FAILED = 4;
+  }
+
+  /* Current lockdown state being reported. */
+  State state = 1;
+
+  /*
+   * For LOCKED: machine-readable reason. Known values:
+   *   "needs_auth"        — storage already unlocked, client must auth
+   *   "token_missing"     — no boot token on flash
+   *   "token_expired"     — boot token wall-clock TTL elapsed
+   *   "token_boots_zero"  — boot token boot-count TTL exhausted
+   *   "token_hmac_fail"   — token tampered or wrong device
+   *   "token_dek_fail"    — token DEK decrypt failed
+   *   "token_wrong_size"  — token file corrupted
+   *   "token_bad_magic"   — token file corrupted
+   *   "not_provisioned"   — should generally use NEEDS_PROVISION state instead
+   * Other values may be added; clients should treat unknown values as
+   * "locked, ask for passphrase".
+   */
+  string lock_reason = 2;
+
+  /*
+   * For UNLOCKED: remaining boots on the issued session token.
+   * Decrements by 1 on each subsequent boot.
+   */
+  uint32 boots_remaining = 3;
+
+  /*
+   * For UNLOCKED: wall-clock expiry of the issued session token,
+   * absolute Unix-epoch seconds. 0 = no time limit.
+   */
+  uint32 valid_until_epoch = 4;
+
+  /*
+   * For UNLOCK_FAILED: seconds the client must wait before another
+   * passphrase attempt will be accepted. 0 = wrong passphrase, no
+   * backoff (immediate retry allowed but advisable to prompt user).
+   */
+  uint32 backoff_seconds = 5;
+}
+
 /*
  * A notification message from the device to the client
  * To be used for important messages that should to be displayed to the user
