Merge pull request #678 from Foundation-Devices/SFT-8071-psbt-parsing-rejects-unknown-fields
What changed, and why it matters
This firmware update fixes how Passport handles partially-signed Bitcoin transactions (PSBTs) that contain fields the device does not recognize. Previously, unknown fields could accidentally be interpreted as known Taproot key-derivation data, which could corrupt the transaction or leak path information. The patch makes all unrecognized fields pass through unchanged, adds support for the standard PSBT version field, and rejects unsupported PSBT versions. It also adds unit tests to verify the behavior.
Treat as a security-relevant hardening fix. Review whether prior firmware versions could be coerced into mis-serializing unknown Taproot-like fields, and consider whether a CVE or advisory is warranted if transaction integrity or key-path privacy could be affected. Users should upgrade to a firmware containing this commit.
Security signals we found
PSBT unknown-field type confusion between maps could lead to misinterpretation of attacker-controlled data as Taproot derivation info
Missing PSBT version handling could allow future-version PSBTs to be parsed with undefined semantics
Added explicit rejection of malformed and duplicate PSBT_GLOBAL_VERSION fields
Unknown fields now bypass type-specific serialization, preventing structured decoding of opaque data
Unit tests added for unknown-field round-trip fidelity and version validation
Evidence from the diff
The commit modifies the PSBT parser in Passport firmware. It renames the internal ‘unknown’ dictionary to ‘unknowns’ and ensures unknown fields are serialized with raw=True so they are not decoded as Taproot BIP32 derivation tuples (PSBT_IN_TAP_BIP32_DERIVATION / PSBT_OUT_TAP_BIP32_DERIVATION). It adds PSBT_GLOBAL_VERSION (0xfb) parsing, only accepts version 0, rejects malformed or duplicate version fields, and preserves an explicit version 0 on export. Unit tests verify unknown/proprietary fields survive round-trips and that unsupported/malformed versions are rejected.
Changed components
ports/stm32/boards/Passport/modules/psbt.pyports/stm32/boards/Passport/modules/public_constants.pyports/stm32/boards/Passport/modules/tests/test_unit.pyports/stm32/boards/Passport/modules/tests/unit/psbt_unknown_globals.pyports/stm32/boards/Passport/modules/tests/unit/psbt_versions.pyInspect captured patch +168 / −16
### ports/stm32/boards/Passport/modules/psbt.py
@@ -28,7 +28,7 @@
from taproot import output_script, tagged_hash
from public_constants import (
- PSBT_GLOBAL_UNSIGNED_TX, PSBT_GLOBAL_XPUB, PSBT_IN_NON_WITNESS_UTXO, PSBT_IN_WITNESS_UTXO,
+ PSBT_GLOBAL_UNSIGNED_TX, PSBT_GLOBAL_XPUB, PSBT_GLOBAL_VERSION, PSBT_IN_NON_WITNESS_UTXO, PSBT_IN_WITNESS_UTXO,
PSBT_IN_PARTIAL_SIG, PSBT_IN_SIGHASH_TYPE, PSBT_IN_REDEEM_SCRIPT,
PSBT_IN_WITNESS_SCRIPT, PSBT_IN_BIP32_DERIVATION, PSBT_IN_FINAL_SCRIPTSIG,
PSBT_IN_FINAL_SCRIPTWITNESS, PSBT_OUT_REDEEM_SCRIPT, PSBT_OUT_WITNESS_SCRIPT,
@@ -149,11 +149,11 @@ class psbtProxy:
no_keys = ()
# these fields will return None but are not stored unless a value is set
- blank_flds = ('unknown', 'subpaths', 'tap_subpaths')
+ blank_flds = ('unknowns', 'subpaths', 'tap_subpaths')
def __init__(self):
self.fd = None
- self.unknown = {}
+ self.unknowns = {}
def __getattr__(self, nm):
if nm in self.blank_flds:
@@ -196,14 +196,16 @@ def parse(self, fd):
self.store(kt, bytes(key), proxy)
- def write(self, out_fd, ktype, val, key=b''):
+ def write(self, out_fd, ktype, val, key=b'', raw=False):
# serialize helper: write w/ size and key byte
out_fd.write(ser_compact_size(1 + len(key)))
out_fd.write(bytes([ktype]))
out_fd.write(key)
if isinstance(val, tuple):
- if ktype in (PSBT_IN_TAP_BIP32_DERIVATION, PSBT_OUT_TAP_BIP32_DERIVATION):
+ # Unknown fields always contain file offsets, even when their type
+ # number matches a known field in another PSBT map.
+ if not raw and ktype in (PSBT_IN_TAP_BIP32_DERIVATION, PSBT_OUT_TAP_BIP32_DERIVATION):
path, tap_hashes = val
output = ser_compact_size(len(tap_hashes))
for h in tap_hashes:
@@ -318,7 +320,7 @@ def parse_subpaths(self, my_xfp):
#
class psbtOutputProxy(psbtProxy):
no_keys = {PSBT_OUT_REDEEM_SCRIPT, PSBT_OUT_WITNESS_SCRIPT}
- blank_flds = ('unknown', 'subpaths', 'redeem_script', 'witness_script',
+ blank_flds = ('unknowns', 'subpaths', 'redeem_script', 'witness_script',
'is_change', 'num_our_keys', 'tap_internal_key', 'tap_tree',
'tap_subpaths')
@@ -354,7 +356,7 @@ def store(self, kt, key, val):
self.tap_subpaths = {}
self.tap_subpaths[key[1:]] = val
else:
- self.unknown[key] = val
+ self.unknowns[key] = val
def serialize(self, out_fd, my_idx):
@@ -381,8 +383,8 @@ def wr(*a):
for k in self.tap_subpaths:
wr(PSBT_OUT_TAP_BIP32_DERIVATION, self.tap_subpaths[k], k)
- for k in self.unknown:
- wr(k[0], self.unknown[k], k[1:])
+ for k in self.unknowns:
+ self.write(out_fd, k[0], self.unknowns[k], k[1:], raw=True)
def validate(self, out_idx, txo, my_xfp, active_multisig):
# Do things make sense for this output?
@@ -531,7 +533,7 @@ class psbtInputProxy(psbtProxy):
PSBT_IN_FINAL_SCRIPTWITNESS, PSBT_IN_TAP_KEY_SIG, PSBT_IN_TAP_INTERNAL_KEY,
PSBT_IN_TAP_MERKLE_ROOT}
- blank_flds = ('unknown',
+ blank_flds = ('unknowns',
'utxo', 'witness_utxo', 'sighash',
'redeem_script', 'witness_script', 'fully_signed',
'is_segwit', 'is_multisig', 'is_p2sh', 'num_our_keys',
@@ -926,7 +928,7 @@ def store(self, kt, key, val):
self.tap_merkle_root = val
else:
# including: PSBT_IN_FINAL_SCRIPTSIG, PSBT_IN_FINAL_SCRIPTWITNESS
- self.unknown[key] = val
+ self.unknowns[key] = val
def serialize(self, out_fd, my_idx):
# Output this input's values; might include signatures that weren't there before
@@ -968,8 +970,8 @@ def wr(*a):
if self.tap_internal_key:
wr(PSBT_IN_TAP_INTERNAL_KEY, self.tap_internal_key)
- for k in self.unknown:
- wr(k[0], self.unknown[k], k[1:])
+ for k in self.unknowns:
+ self.write(out_fd, k[0], self.unknowns[k], k[1:], raw=True)
class psbtObject(psbtProxy):
@@ -982,6 +984,7 @@ def __init__(self):
# global objects
self.txn = None
+ self.psbt_version = None # Absent means version 0; preserve explicit 0 on export.
self.xpubs = [] # tuples(xfp_path, xpub)
from common import settings
@@ -1030,6 +1033,16 @@ def store(self, kt, key, val):
# list of tuples(xfp_path, xpub)
self.xpubs.append((self.get(val), key[1:]))
assert len(self.xpubs) <= MAX_SIGNERS
+ elif kt == PSBT_GLOBAL_VERSION:
+ if len(key) != 1 or val[1] != 4:
+ raise FatalPSBTIssue('Invalid PSBT version field')
+ if self.psbt_version is not None:
+ raise FatalPSBTIssue('Duplicate PSBT version field')
+ # BIP174: no key data and exactly four little-endian version bytes.
+ # This parser supports only v0, whether explicit or omitted.
+ if self.get(val) != b'\x00\x00\x00\x00':
+ raise FatalPSBTIssue('Unsupported PSBT version')
+ self.psbt_version = 0
else:
self.unknowns[key] = val
@@ -1646,9 +1659,12 @@ def wr(*a):
for v, k in self.xpubs:
wr(PSBT_GLOBAL_XPUB, v, k)
- if self.unknown:
- for k in self.unknown:
- wr(k[0], self.unknown[k], k[1:])
+ if self.psbt_version is not None:
+ wr(PSBT_GLOBAL_VERSION, pack('<I', self.psbt_version))
+
+ if self.unknowns:
+ for k in self.unknowns:
+ self.write(out_fd, k[0], self.unknowns[k], k[1:], raw=True)
# sep between globals and inputs
out_fd.write(b'\0')
### ports/stm32/boards/Passport/modules/public_constants.py
@@ -82,6 +82,7 @@
#
PSBT_GLOBAL_UNSIGNED_TX = const(0)
PSBT_GLOBAL_XPUB = const(1)
+PSBT_GLOBAL_VERSION = const(0xfb)
PSBT_IN_NON_WITNESS_UTXO = const(0)
PSBT_IN_WITNESS_UTXO = const(1)
### ports/stm32/boards/Passport/modules/tests/test_unit.py
@@ -96,6 +96,14 @@ def test_psbt_amounts(test):
assert test('psbt_amounts.py') == b'OK'
+def test_psbt_unknown_globals(test):
+ assert test('psbt_unknown_globals.py') == b'OK'
+
+
+def test_psbt_versions(test):
+ assert test('psbt_versions.py') == b'OK'
+
+
def test_multisig_xpub_validation(test):
assert test('multisig_xpub_validation.py') == b'OK'
### ports/stm32/boards/Passport/modules/tests/unit/psbt_unknown_globals.py
@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: © 2026 Foundation Devices, Inc. <hello@foundation.xyz>
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Unknown and proprietary fields must survive all PSBT maps without interpretation.
+
+from uio import BytesIO
+from ustruct import pack
+
+import common
+from psbt import psbtObject
+from serializations import CTxOut, ser_string
+
+
+# Unsigned transaction with one input and one output.
+txin = (b'\x11' * 32) + pack('<I', 0) + b'\x00' + pack('<I', 0xffffffff)
+txout = CTxOut(1000, b'\x00\x14' + b'\x22' * 20)
+txn = pack('<i', 2) + b'\x01' + txin + b'\x01' + txout.serialize() + pack('<I', 0)
+unknowns = (
+ (b'\x50extra', b'unknown value'),
+ (b'\xfc\x04test\x00extra', b'proprietary value'),
+)
+# Type 0x16 is a Taproot derivation only in the input map, and 0x07 only
+# in the output map. Elsewhere these opaque values must not be decoded.
+global_fields = unknowns + ((b'\x16collision', b'raw global'), (b'\x07collision', b''))
+input_fields = unknowns + ((b'\x50second', b'\x00\xff' * 100),)
+output_fields = unknowns + ((b'\x16collision', b'raw output'),)
+tap_key = b'\x33' * 32
+tap_path = b'\x00' + pack('<II', 0x12345678, 0)
+
+
+def encode_map(fields):
+ return b''.join(ser_string(key) + ser_string(value) for key, value in fields) + b'\x00'
+
+
+data = b'psbt\xff' + encode_map(((b'\x00', txn),) + global_fields)
+data += encode_map(input_fields + ((b'\x16' + tap_key, tap_path),))
+data += encode_map(output_fields + ((b'\x07' + tap_key, tap_path),))
+
+original_settings = common.settings
+try:
+ common.settings = {}
+ psbt = psbtObject.read_psbt(BytesIO(data))
+ # Known Taproot derivations still use structured serialization.
+ for scope in (psbt.inputs[0], psbt.outputs[0]):
+ assert scope.parse_subpaths(0x12345678) == 1
+
+ # MicroPython dictionaries may serialize the fields in a different order.
+ serialized = BytesIO()
+ psbt.serialize(serialized)
+ serialized.seek(0)
+ reparsed = psbtObject.read_psbt(serialized)
+ for scope in (reparsed.inputs[0], reparsed.outputs[0]):
+ assert scope.parse_subpaths(0x12345678) == 1
+ assert scope.tap_subpaths[tap_key] == ([0x12345678, 0], [])
+finally:
+ common.settings = original_settings
+
+for parsed in (psbt, reparsed):
+ for scope, fields in ((parsed, global_fields), (parsed.inputs[0], input_fields),
+ (parsed.outputs[0], output_fields)):
+ assert len(scope.unknowns) == len(fields)
+ for key, value in fields:
+ assert scope.get(scope.unknowns[key]) == value
+ assert parsed.get(parsed.txn) == txn
+ assert parsed.num_inputs == 1
+ assert parsed.num_outputs == 1
+
+return_value.write(b'OK')
### ports/stm32/boards/Passport/modules/tests/unit/psbt_versions.py
@@ -0,0 +1,59 @@
+# SPDX-FileCopyrightText: © 2026 Foundation Devices, Inc. <hello@foundation.xyz>
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from uio import BytesIO
+from ustruct import pack
+
+import common
+from exceptions import FatalPSBTIssue
+from psbt import psbtObject
+from serializations import CTxOut, ser_string
+
+
+txin = b'\x11' * 32 + pack('<I', 0) + b'\x00' + pack('<I', 0xffffffff)
+txout = CTxOut(1000, b'\x00\x14' + b'\x22' * 20)
+txn = pack('<i', 2) + b'\x01' + txin + b'\x01' + txout.serialize() + pack('<I', 0)
+
+
+def read(fields):
+ data = b'psbt\xff' + ser_string(b'\x00') + ser_string(txn)
+ for key, value in fields:
+ data += ser_string(key) + ser_string(value)
+ return psbtObject.read_psbt(BytesIO(data + b'\x00\x00\x00'))
+
+
+original_settings = common.settings
+try:
+ common.settings = {}
+ for version in (1, 2, 0xffffffff):
+ try:
+ read(((b'\xfb', pack('<I', version)),))
+ except FatalPSBTIssue:
+ pass
+ else:
+ raise AssertionError('Unsupported PSBT version accepted')
+
+ invalid_fields = [((b'\xfb', b'\x00' * length),) for length in (0, 1, 3, 5, 8)]
+ invalid_fields += [((b'\xfbextra', pack('<I', 0)),),
+ ((b'\xfb', pack('<I', 0)), (b'\xfb', pack('<I', 0)))]
+ for fields in invalid_fields:
+ try:
+ read(fields)
+ except FatalPSBTIssue:
+ pass
+ else:
+ raise AssertionError('Malformed PSBT version accepted')
+
+ for fields, expected in (((), None), (((b'\xfb', pack('<I', 0)),), 0)):
+ parsed = read(fields)
+ assert parsed.psbt_version == expected
+ serialized = BytesIO()
+ parsed.serialize(serialized)
+ serialized.seek(0)
+ reparsed = psbtObject.read_psbt(serialized)
+ assert reparsed.psbt_version == expected
+ assert reparsed.get(reparsed.txn) == txn
+finally:
+ common.settings = original_settings
+
+return_value.write(b'OK')Why this scored 63/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.