Skip to content

bip138: clarify key selection and apply exclusions across expressions - #2300

Open
Sjors wants to merge 6 commits into
bitcoin:masterfrom
Sjors:2026/09/bip138-recipients
Open

Sjors wants to merge 6 commits into
bitcoin:masterfrom
Sjors:2026/09/bip138-recipients

Conversation

@Sjors

@Sjors Sjors commented Sep 23, 2026

Copy link
Copy Markdown
Member

This PR clarifies which keys can decrypt a BIP138 backup.

It expands the existing exclusion rule to consider all descriptors and key expressions in the backup. This makes encryption safer, but does not impact decryption, so it's not a breaking change.

Four middle commits:

  • generalize key-selection test vectors: rename keys_types.json to recipient_keys.json and support lists of descriptors and expected keys, preserving the nine existing cases.
  • clarify MuSig participant eligibility: add two vectors, clarify that the participant xpubs should be used, not the aggregate key
  • collect and deduplicate recipient keys across the backup: deduplicate across all descriptor / policy sets.
  • exclude roots exposed by another expression: three test vectors: bare/derived reuse, an opposite-parity literal, and a MuSig participant exposed in a script leaf.

The first commit introduces a changelog. I'm reusing that commit across a few parallel pull requests.

The last commit updates the changelog; I'll update that depending on merge order.

Record the initial published draft using the BIP3 document-version
and changelog convention.
Rename keys_types.json to recipient_keys.json and generalize the format
to support multiple descriptors and multiple recipient keys:

- "key": a single key-expression string becomes "descriptors": an array
  of complete descriptor strings.
- "expected": an x-only key string becomes "expected_keys": an array
  containing that key; null remains null.

Convert the nine existing cases by wrapping each key expression in tr(),
except the uncompressed literal uses pk(), since tr() does not accept it.
Each case has one descriptor.
MuSig aggregation hides participant keys, so account xpubs do not need
individual trailing derivation.

Specify that encryption uses participant roots rather than the aggregate key.

Add MuSig2 test vectors: one for a bare aggregate and one for aggregate
derivation.
A root selected through a derived xpub can also appear bare or as a
literal key. Once a spend reveals it, anyone could decrypt the backup.
Exclude such cases.
@Sjors

Sjors commented Sep 23, 2026

Copy link
Copy Markdown
Member Author

cc @pythcoiner, see also #2298 and #2299

@murchandamus murchandamus left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems reasonable, waiting for @pythcoiner to chime in.

@murchandamus murchandamus added Proposed BIP modification PR by non-owner to update BIP content Pending acceptance This BIP modification requires sign-off by the champion of the BIP being modified labels Sep 23, 2026
Sjors added a commit to Sjors/bitcoin that referenced this pull request Sep 23, 2026
Convert the nine existing key-expression vectors to the descriptor-list
format proposed in bitcoin/bips#2300. Preserve direct key-extraction checks
and exercise backup creation and decryption with the same cases.
Sjors added a commit to Sjors/bitcoin that referenced this pull request Sep 23, 2026
Import the six recipient vectors proposed in bitcoin/bips#2300
(recipient selection).
Check MuSig roots, aggregation derivation, and payload-wide deduplication
through backup creation and decryption with each expected recipient.

For exposed roots, assert Core refusal, including the MuSig script-leaf
case where the proposal permits proceeding with a different recipient.

Replace the standalone MuSig eligibility and exposed-participant checks
with the proposed vectors.
Sjors added a commit to Sjors/bitcoin that referenced this pull request Sep 23, 2026
Convert the nine existing key-expression vectors to the descriptor-list
format proposed in bitcoin/bips#2300. Preserve direct key-extraction checks
and exercise backup creation and decryption with the same cases.
Sjors added a commit to Sjors/bitcoin that referenced this pull request Sep 23, 2026
Import the six recipient vectors proposed in bitcoin/bips#2300
(recipient selection).
Check MuSig roots, aggregation derivation, and payload-wide deduplication
through backup creation and decryption with each expected recipient.

For exposed roots, assert Core refusal, including the MuSig script-leaf
case where the proposal permits proceeding with a different recipient.

Replace the standalone MuSig eligibility and exposed-participant checks
with the proposed vectors.
@pythcoiner

pythcoiner commented Sep 24, 2026

Copy link
Copy Markdown
Contributor

@Sjors, about bip138: exclude roots exposed by another expression I'm wondering if we should not even be more strict: only use keys expressions that have at least a wildcard or a multipath

let's take the example of wsh(or_i(pk(X/0/*),pk(Y))), here Y has not link to X, but the key will end up on chain, so anyone that get the encrypted payload could easily bruteforce by trying all onchain keys?

@Sjors

Sjors commented Sep 24, 2026

Copy link
Copy Markdown
Member Author

@pythcoiner can you explain your example a bit more? IIUC Y is already excluded because it's a bare xpub or pubkey.

@pythcoiner

Copy link
Copy Markdown
Contributor

@Sjors my bad, you are right

@pythcoiner

Copy link
Copy Markdown
Contributor

ACK bf63b1d

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Pending acceptance This BIP modification requires sign-off by the champion of the BIP being modified Proposed BIP modification PR by non-owner to update BIP content

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants