Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
a2a6d81
Verify interactive Taproot anti-exfil transcripts at the HWI boundary
Sjors Oct 25, 2026
5f7b774
ledger: transport nonce commitments for interactive Taproot signing
Sjors Oct 25, 2026
da55aec
test: exercise Ledger anti-exfil through HWI and Bitcoin Core
Sjors Oct 25, 2026
c278dbc
Reject anti-exfil requests before invoking unsupported signers
Sjors Oct 25, 2026
07dadd3
trezorlib: support draft anti-exfil nonce receipts
Sjors Oct 25, 2026
a7b3825
Support draft Taproot anti-exfil in Jade native PSBT signing
Sjors Oct 25, 2026
cbff5e5
coldcard: preserve client method types through exception handling
Sjors Oct 25, 2026
c8c6859
test: expose interactive device suites and run Trezor wire regressions
Sjors Oct 25, 2026
5927ab4
Enable Jade Taproot key-path signing for current firmware
Sjors Oct 25, 2026
b813f4d
test: allow isolated Coldcard simulator sockets
Sjors Oct 25, 2026
7437253
coldcard: support interactive Taproot anti-exfil on Edge
Sjors Oct 25, 2026
db70d06
test: reject mixed Trezor nonce receipts across inputs
Sjors Oct 25, 2026
ef8cf2c
test: activate Jade and Edge interactive suites in the shared runner
Sjors Oct 25, 2026
7b9d5ef
Test refusal of anti-exfil on released Jade firmware
Sjors Oct 25, 2026
531e626
Enable BitBox02 Taproot key-path signing for current firmware
Sjors Oct 25, 2026
1a27b37
Support draft Taproot anti-exfil in the BitBox02 streaming protocol
Sjors Oct 25, 2026
c49b532
test: check multiple anti-exfil proofs and untargeted inputs
Sjors Oct 25, 2026
ed6d3ff
Require BitBox02 anti-exfil capability in the raw SDK
Sjors Oct 25, 2026
9bfdf3c
test: expose the BitBox02 interactive suite in the shared runner
Sjors Oct 25, 2026
bbf9658
Keep anti-exfil device logs and exceptions private to the signing con…
Sjors Oct 25, 2026
4f62896
Protect anti-exfil CLI diagnostics across reconnect and close
Sjors Oct 25, 2026
b83e1d5
trezor: bridge interactive Taproot anti-exfil rounds
Sjors Oct 25, 2026
658a43a
test: exercise Trezor anti-exfil firmware in both models
Sjors Oct 25, 2026
8424ae1
test: keep registered wallet accounts distinct across cases
Sjors Oct 25, 2026
0537236
bitbox02: move draft anti-exfil capability to unused DeviceInfo field
Sjors Oct 25, 2026
9cc5605
Return only verified anti-exfil results in the host PSBT
Sjors Oct 25, 2026
775da41
test: disable unused P2P in the device node
Sjors Oct 25, 2026
fa10417
TEMPORARY: CI build anti-exfil firmware and Core from Sjors forks
Sjors Oct 25, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/actions/build-sim/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ runs:
-o Acquire::https::Timeout=30
)
timeout 5m sudo apt-get "${apt_options[@]}" update
timeout 30m sudo apt-get "${apt_options[@]}" install -y gcc-arm-linux-gnueabihf libsdl2-image-dev libslirp-dev libpcsclite-dev ninja-build libltdl-dev
timeout 30m sudo apt-get "${apt_options[@]}" install -y cmake patchelf libpng-dev gcc-12 gcc-13 gcc-arm-linux-gnueabihf libsdl2-image-dev libslirp-dev libpcsclite-dev ninja-build libltdl-dev
pip install poetry uv
wget https://github.com/protocolbuffers/protobuf/releases/download/v22.0/protoc-22.0-linux-x86_64.zip
sudo unzip protoc-22.0-linux-x86_64.zip -d /usr/local
Expand Down
12 changes: 12 additions & 0 deletions .github/actions/test-device/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,18 @@ runs:
run: |
cd test; poetry run ./run_tests.py --${{ matrix.device }} --interface=${{ matrix.test.interface }} --device-only; cd ..

# TEMPORARY ANTI-EXFIL: execute against the companion firmware/Core forks.
- name: Test interactive anti-exfil
shell: bash
run: |
case "${{ matrix.device }}" in
ledger) anti_exfil_flags=(--ledger-anti-exfil-core) ;;
trezor-1|trezor-t|coldcard-edge|jade|bitbox02) anti_exfil_flags=(--anti-exfil) ;;
*) exit 0 ;;
esac
cd test
poetry run ./run_tests.py --${{ matrix.device }} --device-only --interface=${{ matrix.test.interface }} "${anti_exfil_flags[@]}"

- if: failure()
shell: bash
run: |
Expand Down
18 changes: 18 additions & 0 deletions .github/actions/test-dist/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,24 @@ runs:
run: |
cd test; poetry run ./run_tests.py --${{ matrix.device }} --interface=bindist --device-only; cd ..

# TEMPORARY ANTI-EXFIL: execute against the companion firmware/Core forks.
- name: Test interactive anti-exfil
shell: bash
run: |
case "${{ matrix.device }}" in
ledger) anti_exfil_flags=(--ledger-anti-exfil-core) ;;
trezor-1|trezor-t|coldcard-edge|jade|bitbox02) anti_exfil_flags=(--anti-exfil) ;;
*) exit 0 ;;
esac
interface=cli
runner=(./run_tests.py)
if [[ "${{ matrix.test.script }}" == Bindist ]]; then
interface=bindist
runner=(poetry run ./run_tests.py)
fi
cd test
"${runner[@]}" --${{ matrix.device }} --device-only --interface=${interface} "${anti_exfil_flags[@]}"

- if: failure()
shell: bash
run: |
Expand Down
49 changes: 25 additions & 24 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ concurrency:
group: ${{ github.event_name != 'pull_request' && github.run_id || github.ref }}
cancel-in-progress: true

# TEMPORARY ANTI-EXFIL: retain the tested GCC 12/13 simulator build host.
env:
LC_ALL: 'C.UTF-8'
LANG: 'C.UTF-8'
Expand All @@ -21,7 +22,7 @@ env:
jobs:
non-device-tests:
name: Non-device tests
runs-on: ubuntu-latest
runs-on: ubuntu-24.04
container: python:3.12
steps:
- uses: actions/checkout@v7
Expand All @@ -36,7 +37,7 @@ jobs:

lint:
name: lint
runs-on: ubuntu-latest
runs-on: ubuntu-24.04
container: python:3.12
steps:
- uses: actions/checkout@v7
Expand All @@ -51,7 +52,7 @@ jobs:

wine-builder:
name: Wine builder
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

steps:
- uses: actions/checkout@v7
Expand All @@ -75,7 +76,7 @@ jobs:

dist-builder:
name: Dist builder
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

steps:
- uses: actions/checkout@v7
Expand Down Expand Up @@ -114,7 +115,7 @@ jobs:
with:
sim: trezor
include: ${{ needs.prepare-sim-matrices.outputs.trezor }}
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

sim-builder-coldcard:
name: Coldcard sim builder
Expand All @@ -123,7 +124,7 @@ jobs:
with:
sim: coldcard
include: ${{ needs.prepare-sim-matrices.outputs.coldcard }}
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

sim-builder-coldcard-edge:
name: Coldcard Edge sim builder
Expand All @@ -132,7 +133,7 @@ jobs:
with:
sim: coldcard-edge
include: ${{ needs.prepare-sim-matrices.outputs.coldcard_edge }}
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

sim-builder-bitbox:
name: Bitbox sim builder
Expand All @@ -141,7 +142,7 @@ jobs:
with:
sim: bitbox
include: ${{ needs.prepare-sim-matrices.outputs.bitbox }}
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

sim-builder-jade:
name: Jade sim builder
Expand All @@ -150,7 +151,7 @@ jobs:
with:
sim: jade
include: ${{ needs.prepare-sim-matrices.outputs.jade }}
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

sim-builder-ledger:
name: Ledger sim builder
Expand All @@ -159,7 +160,7 @@ jobs:
with:
sim: ledger
include: ${{ needs.prepare-sim-matrices.outputs.ledger }}
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

sim-builder-keepkey:
name: Keepkey sim builder
Expand All @@ -168,23 +169,23 @@ jobs:
with:
sim: keepkey
include: ${{ needs.prepare-sim-matrices.outputs.keepkey }}
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

ledger-legacy-app-builder:
name: Ledger Bitcoin Legacy App builder
uses: ./.github/workflows/ledger-legacy-app-builder.yml
with:
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

ledger-app-builder:
name: Ledger Bitcoin App builder
uses: ./.github/workflows/ledger-app-builder.yml
with:
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

bitcoind-builder:
name: bitcoind builder
runs-on: ubuntu-latest
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7
- uses: ./.github/actions/build-bitcoind
Expand All @@ -194,68 +195,68 @@ jobs:
needs: [sim-builder-trezor, bitcoind-builder, dist-builder]
with:
device: trezor-1
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

test-trezor-t:
uses: ./.github/workflows/device-test.yml
needs: [sim-builder-trezor, bitcoind-builder, dist-builder]
with:
device: trezor-t
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

test-ledger-legacy:
uses: ./.github/workflows/device-test.yml
needs: [sim-builder-ledger, ledger-legacy-app-builder, bitcoind-builder, dist-builder]
with:
device: ledger-legacy
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

test-ledger:
uses: ./.github/workflows/device-test.yml
needs: [sim-builder-ledger, ledger-app-builder, bitcoind-builder, dist-builder]
with:
device: ledger
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

test-coldcard:
uses: ./.github/workflows/device-test.yml
needs: [sim-builder-coldcard, bitcoind-builder, dist-builder]
with:
device: coldcard
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

test-coldcard-edge:
uses: ./.github/workflows/device-test.yml
needs: [sim-builder-coldcard-edge, bitcoind-builder, dist-builder]
with:
device: coldcard-edge
runs-on: ubuntu-latest
runs-on: ubuntu-24.04
python_versions: '["3.14"]'

test-bitbox01:
uses: ./.github/workflows/device-test.yml
needs: [sim-builder-bitbox, bitcoind-builder, dist-builder]
with:
device: bitbox01
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

test-bitbox02:
uses: ./.github/workflows/device-test.yml
needs: [sim-builder-bitbox, bitcoind-builder, dist-builder]
with:
device: bitbox02
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

test-jade:
uses: ./.github/workflows/device-test.yml
needs: [sim-builder-jade, bitcoind-builder, dist-builder]
with:
device: jade
runs-on: ubuntu-latest
runs-on: ubuntu-24.04

test-keepkey:
uses: ./.github/workflows/device-test.yml
needs: [sim-builder-keepkey, bitcoind-builder, dist-builder]
with:
device: keepkey
runs-on: ubuntu-latest
runs-on: ubuntu-24.04
6 changes: 3 additions & 3 deletions .github/workflows/ledger-app-builder.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@ jobs:
build:
name: Build Bitcoin App
runs-on: ${{ inputs.runs-on }}
# app-bitcoin v2.5.0 targets SDK v26.5.0, provided by builder 5.3.17.
# app-bitcoin develop (2.5.1) is validated with SDK v26.5.0 in builder 5.3.17.
container: ghcr.io/ledgerhq/ledger-app-builder/ledger-app-builder:5.3.17
steps:
- run: |
# Pin to v2.5.0
git clone --branch 2.5.0 --depth 1 https://github.com/LedgerHQ/app-bitcoin.git
# TEMPORARY ANTI-EXFIL: companion fork branch; restore upstream develop after integration.
git clone --branch 2026/10/taproot-anti-exfil https://github.com/Sjors/ledger-bitcoin-app.git app-bitcoin
cd app-bitcoin
make DEBUG=1 COIN=bitcoin_testnet BOLOS_SDK=$NANOX_SDK
- uses: actions/upload-artifact@v7
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/type-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ jobs:
hwilib/_bech32.py
hwilib/_cli.py
hwilib/commands.py
hwilib/anti_exfil.py
hwilib/common.py
hwilib/descriptor.py
hwilib/devices/bitbox02.py
Expand Down
112 changes: 112 additions & 0 deletions docs/usage/anti-exfil.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
Interactive Taproot anti-exfil
=============================

This experimental interface implements the draft single-signer BIP340 anti-exfil
protocol. It requires matching device firmware. It supports Taproot key-path
inputs with ``SIGHASH_DEFAULT`` or ``SIGHASH_ALL``; it does not extend MuSig2,
FROST, or script-path signing.

The host runs ``signtx`` twice. Each requested PSBT input carries proprietary
keys encoded as ``fc 02 61 65 <subtype> <output-key>``. The identifier is ``ae``;
the output key is the 32-byte x-only Taproot output key, rather than its internal
key. Subtype 0 holds a 32-byte host commitment, subtype 1 a compressed 33-byte
device nonce, and subtype 2 the host's 32-byte entropy scalar. These experimental
keys are subject to change during specification review.

In the first call the input contains only the host commitment. The device returns
its original nonce and no signature. The host checks and retains that response,
adds its entropy, and makes the second call. HWI verifies that the signature uses
the committed device nonce plus the host contribution and verifies the BIP340
signature against the original transaction. A missing proof, early signature,
changed transaction, or unsupported device fails instead of returning an
unprotected result. The presence of these fields is an explicit protection
request; there is no fallback to ordinary signing.

Successful protected replies from ``hwilib.commands.signtx`` and the CLI are
private host-local protocol messages. These boundaries validate the raw device
response, then copy only validated nonce receipts or verified target signatures
into the original host request. Original caller metadata and the anti-exfil
transcript are retained; unrelated metadata added, changed or removed by the
device is not forwarded. This handles device-controlled bytes from native PSBT
transports such as Jade and Coldcard; it assumes the application and HWI are
trusted parts of the same host.

The trusted host must retain its original state and verify the device
contributions. A calling application may delegate these checks to the checked
``commands.signtx``/CLI boundary. Core additionally performs its own verification;
Core and HWI remain trusted components of the same host. Before exporting a
completed PSBT, the host must strip the anti-exfil fields and copy verified
signatures into its pristine PSBT. Low-level
``HardwareWalletClient.sign_tx`` and SDK calls expose transport results; direct
callers must perform ``anti_exfil.requests`` / ``anti_exfil.check_response`` and
the same original-PSBT reconstruction themselves.

Generate host entropy with a cryptographically secure random generator and
reject zero or values at or above the secp256k1 group order. Never send the entropy
before receiving the device nonce. Keep the transcript private and retain the
same entropy and device commitment on retries. Do not automatically retry an
aborted exchange with fresh entropy. An ordinary ``signtx`` request without these
fields retains its existing behavior.

Protected signing suppresses SDK/device logs only in the active signing context
and returns fixed device-error messages. Cancellation, unavailable-action and
connection categories remain distinguishable. Logs from unrelated application
threads keep their normal behavior. This also protects debug tracebacks from
chained SDK errors containing the nonce transcript.

Library callers that construct and close clients themselves can include that
whole lifetime in ``hwilib.anti_exfil.private_operation()``. The ``signtx``
command guards its device call; a surrounding scope also covers reconnect and
close diagnostics from a previous signing round. The CLI automatically covers
client initialization, signing and close when it recognizes an explicit
anti-exfil PSBT. Device errors use controlled messages throughout that lifetime,
including when ``--debug`` is enabled. A cleanup failure returns an error without
also returning the signing transcript.

The first firmware integration uses the Ledger Bitcoin app with its draft
anti-exfil extension. Its round-1 nonce is transported with yield tag
``0xfffffffd``, followed by the input index, compressed nonce, and x-only key.
Stock firmware is not claimed to support this extension.

To exercise matching firmware in Speculos, run from ``test/``::

python run_tests.py --ledger-anti-exfil --interface=library \
--ledger-path=/absolute/path/to/speculos.py \
--bitcoind=/absolute/path/to/bitcoind

The opt-in test covers DEFAULT and ALL, deterministic commitment retries,
firmware rejection of mismatched openings, host verification, mempool acceptance,
broadcast, and confirmation. The normal non-device test suite includes shared
cryptographic vectors and rejection tests for malformed or malicious responses.

To include the full Bitcoin Core host -> HWI subprocess -> Ledger path, add
``--ledger-anti-exfil-core`` and point ``--bitcoind`` at the matching Core build
with ``-signerantiexfil`` support. The test starts an independent node with that
setting enabled, creates an external-signer wallet, exercises
``walletprocesspsbt`` and ``send``, checks transcript removal, and confirms the
broadcast transaction.

Trezor One and T firmware with the provisional ``BitcoinAntiExfil`` capability
uses the same PSBT transcript. The bridge carries it in optional Bitcoin input
fields and returns commitment receipts separately from signatures. The bridge
rejects protection requests before signing when firmware lacks that capability.

Run either matching emulator's interactive suite using ``--anti-exfil`` with
``--trezor-1`` or ``--trezor-t`` and its corresponding path option. Run the
ordinary device suite separately without ``--anti-exfil``; it checks ordinary
signing as well as rejection on devices without the capability.

The same ``--anti-exfil`` option selects the Jade or Coldcard Edge interactive
suite with ``--jade`` or ``--coldcard-edge`` and its corresponding path option.
Jade uses its native PSBT command and advertises ``JADE_TAPROOT_ANTI_EXFIL``.
Coldcard Edge carries the fields through its existing PSBT upload protocol and
requires the matching native ``libngu`` extension. Ordinary Coldcard firmware,
BitBox01, KeepKey, and the legacy Ledger app reject protection requests before
signing. Full device suites include this unsupported-device check.

BitBox02's matching firmware and bundled SDK use an explicit invocation-wide
round and dedicated per-input Taproot fields in the streaming transaction API.
The driver and raw SDK require the advertised capability and do not reuse the
ECDSA anti-klepto channel for Schnorr. ``--bitbox02 --anti-exfil`` selects its
interactive suite. Released firmware is tested to reject the request before
starting a signing exchange.
Loading
Loading