Merge pull request #724 from Foundation-Devices/sft-8255-passport-core-validate-unauthenticated-timestamp-read
What changed, and why it matters
This commit tightens how the Passport hardware wallet checks the firmware timestamp stored in its secure element during firmware updates. Previously, the device read the timestamp from encrypted storage but did not verify that the stored block was authentic and fresh. The patch adds a cryptographic check (pairing unlock + MAC verification) before trusting the timestamp, and makes production builds fail the update if the timestamp cannot be read or verified. It also adds tests that simulate tampered or stale secure-element responses. In plain terms: the wallet now makes sure the 'minimum allowed firmware version' number it uses during updates hasn't been forged or replayed by an attacker.
Treat this as a security-hardening fix with defensive value against potential downgrade or rollback attacks during firmware updates. Review whether any earlier firmware version allowed updates to proceed with an unverified timestamp, and consider whether a security advisory or firmware release note is warranted. Users should update to a firmware release containing this commit.
Security signals we found
Adds cryptographic authentication (pairing unlock + CheckMac) for a previously encrypted-but-unauthenticated firmware timestamp read
Treats a zero/unverifiable timestamp as a hard failure in production builds
Zeros sensitive buffer on every failure path to reduce information leakage
Adds native unit tests that simulate tampered and stale secure-element MAC responses
Centralizes minimum-firmware-timestamp retrieval so both header and signature verification paths enforce the same policy
Evidence from the diff
The change centers on se_get_firmware_timestamp() in ports/stm32/boards/Passport/common/se.c. After the encrypted read of the 32-byte firmware-timestamp slot, the code now calls se_pair_unlock() and se_checkmac_hard(KEYNUM_firmware_timestamp, buf). If either fails, the buffer is zeroed and the function returns 0. A new helper get_minimum_firmware_timestamp() in modpassport.c centralizes the read and, in PRODUCTION_BUILD, raises a RuntimeError when the timestamp is 0. Both verify_update_header() and verify_update_signatures() now use this helper. The Python update flow catches the new RuntimeError and shows a non-recoverable error page. A new test file exercises the native code with mocked secure-element responses, including read failures, unlock failures, nonce/gendig/mac failures, invalid MACs, and stale MACs.
Changed components
Secure-element firmware-timestamp read path (`se_get_firmware_timestamp` in `ports/stm32/boards/Passport/common/se.c`)Native MicroPython module for firmware update verification (`ports/stm32/boards/Passport/modpassport.c`)Python firmware-update flow (`ports/stm32/boards/Passport/modules/flows/update_firmware_flow.py`)Firmware update header and signature verification functions (`verify_update_header`, `verify_update_signatures`)New test harness (`ports/stm32/boards/Passport/modules/tests/test_firmware_timestamp.py`)Inspect captured patch +279 / −12
### CHANGELOG.md
@@ -5,6 +5,7 @@ SPDX-License-Identifier: GPL-3.0-or-later
-->
## Head
+- Improve firmware-update state validation
- Clarify the error when change-address ownership cannot be verified
- Complete change-address verification before transaction review
- Identify network fees from unverifiable PSBT inputs as unverified
### ports/stm32/boards/Passport/common/se.c
@@ -1189,6 +1189,13 @@ uint32_t se_get_firmware_timestamp(uint8_t* board_hash) {
int rc = se_encrypted_read(KEYNUM_firmware_timestamp, KEYNUM_firmware_hash, board_hash, buf, sizeof(buf));
if (rc < 0) {
printf("ERROR: Unable to read firmware timestamp: rec=%d\r\n", rc);
+ memzero(buf, sizeof(buf));
+ return 0;
+ }
+
+ // Verify the complete stored block before using its timestamp.
+ if (se_pair_unlock() < 0 || se_checkmac_hard(KEYNUM_firmware_timestamp, buf) < 0) {
+ memzero(buf, sizeof(buf));
return 0;
}
@@ -1198,6 +1205,7 @@ uint32_t se_get_firmware_timestamp(uint8_t* board_hash) {
#endif
memcpy(&firmware_timestamp, buf, sizeof(uint32_t));
+ memzero(buf, sizeof(buf));
#ifdef DEBUG_PRINT_FW_TIMESTAMP
printf("GET: firmware_timestamp=%lu\r\n", firmware_timestamp);
### ports/stm32/boards/Passport/modpassport.c
@@ -79,6 +79,19 @@ STATIC mp_obj_t mod_passport_verify_supply_chain_server_signature(mp_obj_t hash_
STATIC MP_DEFINE_CONST_FUN_OBJ_2(mod_passport_verify_supply_chain_server_signature_obj,
mod_passport_verify_supply_chain_server_signature);
+STATIC uint32_t get_minimum_firmware_timestamp(void) {
+ uint8_t current_board_hash[HASH_LEN] = {0};
+ get_current_board_hash(current_board_hash);
+
+ uint32_t firmware_timestamp = se_get_firmware_timestamp(current_board_hash);
+#ifdef PRODUCTION_BUILD
+ if (firmware_timestamp == 0) {
+ mp_raise_msg(&mp_type_RuntimeError, MP_ERROR_TEXT("Unable to read firmware timestamp."));
+ }
+#endif
+ return firmware_timestamp;
+}
+
/// def verify_update_header(self, header: bytearray) -> None:
/// '''
/// Verify the given firmware header bytes as a potential candidate to be
@@ -90,12 +103,7 @@ STATIC mp_obj_t mod_passport_verify_update_header(mp_obj_t header) {
mp_buffer_info_t header_info;
mp_get_buffer_raise(header, &header_info, MP_BUFFER_READ);
- // Build the current board hash so we can get the minimum firmware
- // timestamp
- uint8_t current_board_hash[HASH_LEN] = {0};
- get_current_board_hash(current_board_hash);
-
- uint32_t firmware_timestamp = se_get_firmware_timestamp(current_board_hash);
+ uint32_t firmware_timestamp = get_minimum_firmware_timestamp();
FirmwareResult result = {0};
foundation_firmware_verify_update_header(header_info.buf,
@@ -196,12 +204,7 @@ STATIC mp_obj_t mod_passport_verify_update_signatures(mp_obj_t header, mp_obj_t
mp_buffer_info_t validation_hash_info;
mp_get_buffer_raise(validation_hash, &validation_hash_info, MP_BUFFER_READ);
- // Build the current board hash so we can get the minimum firmware
- // timestamp
- uint8_t current_board_hash[HASH_LEN] = {0};
- get_current_board_hash(current_board_hash);
-
- uint32_t firmware_timestamp = se_get_firmware_timestamp(current_board_hash);
+ uint32_t firmware_timestamp = get_minimum_firmware_timestamp();
se_pair_unlock();
bool has_user_key = false;
### ports/stm32/boards/Passport/modules/flows/update_firmware_flow.py
@@ -87,6 +87,10 @@ async def show_firmware_details(self):
await ErrorPage(text='Firmware update is invalid.\n\n{}'.format(str(e))).show()
self.set_result(False)
return
+ except RuntimeError as e:
+ await ErrorPage(text='Firmware update cannot continue.\n\n{}'.format(str(e))).show()
+ self.set_result(False)
+ return
if is_user_signed:
pubkey_result, pubkey = read_user_firmware_pubkey()
### ports/stm32/boards/Passport/modules/tests/test_firmware_timestamp.py
@@ -0,0 +1,251 @@
+# SPDX-FileCopyrightText: © 2026 Foundation Devices, Inc. <hello@foundation.xyz>
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Exercise native firmware-state checks with controlled SE responses."""
+
+import ast
+import asyncio
+from contextlib import nullcontext
+import hashlib
+import os
+from pathlib import Path
+import shlex
+import subprocess
+import sys
+from types import SimpleNamespace
+
+import pytest
+
+from test_supply_chain_bounds import extract_between
+
+
+BOARD = Path(__file__).resolve().parents[2]
+
+
+def function(source, prefix):
+ return prefix + extract_between(source, prefix, '\n}\n', 'native source') + '\n}\n'
+
+
+def compile_and_run(tmp_path, source, production, extra_sources=()):
+ harness = tmp_path / 'firmware_state.c'
+ harness.write_text(source)
+ binary = tmp_path / 'firmware_state'
+ flags = ['-DPRODUCTION_BUILD'] if production else ['-Wno-unused-parameter']
+ subprocess.run(shlex.split(os.environ.get('CC', 'cc')) +
+ ['-std=c99', '-Wall', '-Wextra', '-Werror', '-g'] + flags +
+ ['-I', str(BOARD / 'include'), str(harness)] +
+ [str(path) for path in extra_sources] + ['-o', str(binary)], check=True)
+ subprocess.run([str(binary)], check=True)
+
+
+@pytest.mark.parametrize('production', [True, False])
+def test_timestamp_read_verification(tmp_path, production):
+ native = (BOARD / 'common/se.c').read_text()
+ names = ['int se_pick_nonce(', 'int se_gendig_slot(', 'bool se_is_correct_tempkey(',
+ 'int se_checkmac_hard(', 'uint32_t se_get_firmware_timestamp(']
+ functions = '\n'.join(function(native, name) for name in names)
+
+ timestamp = 1700000000
+ block = timestamp.to_bytes(4, 'little') + bytes(28)
+ serial = bytes.fromhex('0123456789abcdefee')
+ # Independent SHA-256 fixtures for the existing Nonce/GenDig/MAC sequence.
+ responses = []
+ for sequence in range(32):
+ nonce = hashlib.sha256(b'R' * 32 + bytes([sequence]) * 20 + b'\x16\x00\x00').digest()
+ digest = hashlib.sha256(block + b'\x15\x02\x0b\x00\xee\x01\x23' + bytes(25) + nonce).digest()
+ mac = hashlib.sha256(b'P' * 32 + digest + b'\x08\x41\x01' + bytes(12) + b'\xee' +
+ serial[4:8] + serial[:4]).digest()
+ responses.append('{' + ', '.join(str(value) for value in mac) + '}')
+ source = r'''
+#include <assert.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+#include "se.h"
+#include "se-config.h"
+#include "sha256.h"
+#undef LV_REFRESH
+#define LV_REFRESH() ((void)0)
+static struct {
+ uint8_t pairing_secret[32];
+ uint8_t se_serial_number[9];
+} secrets;
+#define rom_secrets (&secrets)
+enum failure { NONE, READ, UNLOCK, NONCE, GENDIG, MAC, INVALID_MAC, STALE_MAC };
+static enum failure failure;
+static uint8_t candidate[32], previous_mac[32];
+static unsigned sequence, command, read_calls, unlock_calls, clear_calls;
+static const uint32_t expected_timestamp = ''' + str(timestamp) + r''';
+static const uint8_t mac_responses[32][32] = {
+''' + ',\n'.join(responses) + r'''
+};
+void rng_buffer(uint8_t* out, size_t len) {
+ sequence++;
+ assert(sequence < 32);
+ memset(out, sequence, len);
+}
+void se_write(seopcode_t op, uint8_t p1, uint16_t p2, uint8_t* data, uint8_t len) {
+ command = op;
+ if (op == OP_Nonce) {
+ assert(p1 == 0 && p2 == 0 && len == 20);
+ for (unsigned i = 0; i < len; i++) assert(data[i] == sequence);
+ } else if (op == OP_GenDig) {
+ assert(p1 == 2 && p2 == KEYNUM_firmware_timestamp && len == 0);
+ } else {
+ assert(op == OP_MAC && p1 == 0x41 && p2 == KEYNUM_pairing_secret && len == 0);
+ }
+}
+int se_read(uint8_t* out, uint8_t len) {
+ assert(len == 32);
+ if (command == OP_Nonce) {
+ if (failure == NONCE) return -1;
+ memset(out, 'R', len);
+ } else {
+ assert(command == OP_MAC);
+ if (failure == MAC) return -1;
+ memcpy(out, failure == STALE_MAC ? previous_mac : mac_responses[sequence], len);
+ if (failure == INVALID_MAC) out[0] ^= 1;
+ if (failure == NONE) memcpy(previous_mac, out, len);
+ }
+ return 0;
+}
+int se_read1(void) { return failure == GENDIG ? -1 : 0; }
+void se_sleep(void) {}
+int se_pair_unlock(void) { unlock_calls++; return failure == UNLOCK ? -1 : 0; }
+int se_encrypted_read(int slot, int keynum, const uint8_t* key, uint8_t* out, int len) {
+ assert(slot == KEYNUM_firmware_timestamp && keynum == KEYNUM_firmware_hash);
+ assert(key != NULL && len == 32);
+ read_calls++;
+ memcpy(out, candidate, len);
+ return failure == READ ? -1 : 0;
+}
+static bool check_equal(const void* a, const void* b, int len) { return memcmp(a, b, len) == 0; }
+void memzero(void* data, size_t len) {
+ assert(len == 32);
+ memset(data, 0, len);
+ clear_calls++;
+}
+''' + functions + r'''
+int main(void) {
+ uint8_t board_hash[32] = {0};
+ memset(secrets.pairing_secret, 'P', 32);
+ const uint8_t serial[9] = {1, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0xee};
+ memcpy(secrets.se_serial_number, serial, sizeof(serial));
+ memcpy(candidate, &expected_timestamp, sizeof(expected_timestamp));
+#ifdef PRODUCTION_BUILD
+ assert(se_get_firmware_timestamp(board_hash) == expected_timestamp);
+ assert(read_calls == 1 && unlock_calls == 1 && sequence == 1 && clear_calls == 1);
+ assert(se_get_firmware_timestamp(board_hash) == expected_timestamp);
+ assert(sequence == 2);
+
+ candidate[0] ^= 1;
+ assert(se_get_firmware_timestamp(board_hash) == 0);
+ candidate[0] ^= 1;
+ candidate[31] = 1;
+ assert(se_get_firmware_timestamp(board_hash) == 0);
+ candidate[31] = 0;
+
+ for (enum failure f = READ; f <= STALE_MAC; f++) {
+ failure = f;
+ unsigned cleared_before = clear_calls;
+ assert(se_get_firmware_timestamp(board_hash) == 0);
+ assert(clear_calls == cleared_before + 1);
+ }
+ failure = NONE;
+ assert(se_get_firmware_timestamp(board_hash) == expected_timestamp);
+#else
+ assert(se_get_firmware_timestamp(board_hash) == 0);
+ assert(read_calls == 0 && unlock_calls == 0 && sequence == 0 && clear_calls == 0);
+#endif
+ return 0;
+}
+'''
+ compile_and_run(tmp_path, source, production, [BOARD / 'common/sha256.c'])
+
+
+@pytest.mark.parametrize('production', [True, False])
+def test_update_timestamp_failure_handling(tmp_path, production):
+ native = (BOARD / 'modpassport.c').read_text()
+ helper = function(native, 'STATIC uint32_t get_minimum_firmware_timestamp(')
+ source = r'''
+#include <assert.h>
+#include <setjmp.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <string.h>
+#define STATIC static
+#define HASH_LEN 32
+#define MP_ERROR_TEXT(x) (x)
+static int mp_type_RuntimeError;
+static jmp_buf error;
+static uint32_t timestamp;
+static void get_current_board_hash(uint8_t* out) { memset(out, 0x42, HASH_LEN); }
+static uint32_t se_get_firmware_timestamp(uint8_t* hash) {
+ for (unsigned i = 0; i < HASH_LEN; i++) assert(hash[i] == 0x42);
+ return timestamp;
+}
+void mp_raise_msg(const void* type, const char* message) {
+ assert(type == &mp_type_RuntimeError);
+ assert(strcmp(message, "Unable to read firmware timestamp.") == 0);
+ longjmp(error, 1);
+}
+''' + helper + r'''
+int main(void) {
+ timestamp = 1700000000;
+ assert(get_minimum_firmware_timestamp() == timestamp);
+ timestamp = 0;
+ if (setjmp(error) == 0) {
+ assert(get_minimum_firmware_timestamp() == 0);
+#ifdef PRODUCTION_BUILD
+ assert(false);
+#endif
+ } else {
+#ifndef PRODUCTION_BUILD
+ assert(false);
+#endif
+ }
+ return 0;
+}
+'''
+ compile_and_run(tmp_path, source, production)
+ for name in ['STATIC mp_obj_t mod_passport_verify_update_header(',
+ 'STATIC mp_obj_t mod_passport_verify_update_signatures(']:
+ wrapper = function(native, name)
+ assert wrapper.index('get_minimum_firmware_timestamp()') < wrapper.index('foundation_firmware_verify_')
+
+
+def test_header_state_failure_is_recoverable(tmp_path, monkeypatch):
+ source = ast.parse((BOARD / 'modules/flows/update_firmware_flow.py').read_text())
+ flow_class = next(node for node in source.body if isinstance(node, ast.ClassDef))
+ method = next(node for node in flow_class.body if node.name == 'show_firmware_details')
+ messages, results = [], []
+
+ class ErrorPage:
+ def __init__(self, text):
+ messages.append(text)
+
+ async def show(self):
+ return True
+
+ def verify_header(_):
+ raise RuntimeError('Unable to read firmware timestamp.')
+
+ header_size = 2048
+ path = tmp_path / 'firmware.bin'
+ path.write_bytes(bytes(header_size))
+ flow = SimpleNamespace(update_file_path=str(path), set_result=results.append)
+ monkeypatch.setitem(sys.modules, 'common', SimpleNamespace())
+ namespace = {
+ 'CardSlot': nullcontext,
+ 'ErrorPage': ErrorPage,
+ 'FW_HEADER_SIZE': header_size,
+ 'FW_MAX_SIZE': header_size,
+ 'passport': SimpleNamespace(InvalidFirmwareUpdate=ValueError, verify_update_header=verify_header),
+ }
+ isolated = ast.Module(body=[method], type_ignores=[])
+ exec(compile(isolated, 'update_firmware_flow.py', 'exec'), namespace)
+ asyncio.run(namespace['show_firmware_details'](flow))
+ assert results == [False]
+ assert messages == ['Firmware update cannot continue.\n\nUnable to read firmware timestamp.']
+ assert not hasattr(flow, 'update_header')Why this scored 69/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.