Bip draft: Bitcoin Encrypted Backup #1951

pythcoiner · 2025-09-04T06:47:33Z

This is a bip for encrypted backup, an encryption scheme for bitcoin wallet related metadata.

Mailing list post: https://groups.google.com/g/bitcoindev/c/5NgJbpVDgEc

bip-encrypted-backup.md

Sjors · 2025-09-04T08:10:03Z

bip-encrypted-backup.md

+| 0x01   | BIP-0380 Descriptor (string)           |
+| 0x02   | BIP-0388 Wallet policy (string)        |
+| 0x03   | BIP-0329 Labels (JSONL)                |
+| 0x04   | Wallet backup (JSON)                   |


Maybe point out that unlisted types should still be decrypted and that new types may be added to the BIP.

That said, a more generic approach would be to allow a bit more space for the type. E.g. a ~4 digit number that must represent a BIP number. Or a short string like "BIP-0329". Both avoid the need to maintain a central register.

Also, if you allow multiple pieces of content in a single encrypted blob, it's useful to have a padding type.

bip-encrypted-backup.md

pythcoiner · 2025-09-04T09:42:45Z

thanks for the review! will address comments tmr!

Sjors · 2025-09-04T12:52:31Z

Open questions

Deterministic nonce: Currently the nonce is generated randomly. Is it safe to produce a deterministic nonce, e.g. hash("NONCE" || plaintext || key_1 || … || key_n), or are there known security concerns with this approach?

In general nonce reuse is unsafe because if you make multiple backups over time, e.g. as you add more transaction labels, you would be reusing the nonce with different message. By including the plaintext in the nonce, you do address that concern.

However it still seems unwise to mess with cryptographic standards. It doesn't seem worth the risk for saving 32 bytes on something that's going to be at least a few hundred bytes for a typical multisig.

shocknet-justin · 2025-09-04T17:09:38Z

Concept ACK, seems adjacent to how some lightning tools enable users to recover SCB's with just their seed to identify and decrypt the backup. Makes sense for descriptors to have something similar.

Sjors · 2025-09-05T06:59:06Z

Concept ACK

pythcoiner · 2025-09-05T09:50:54Z

(not yet finish addressing comments)

bip-encrypted-backup.md

KeysSoze · 2025-09-09T21:57:53Z

Hi @pythcoiner,

By coincidence, two weeks ago I started working on a proposal for a "Standard Encrypted Wallet Payload" to be placed inside an "Encrypted Envelope". The "Wallet Payload" contains descriptors and metadata but can also act as a full wallet backup including transactions, UTXOs and addresses. The proposal is very much a work in progress.

I only just found this discussion so am reading through it to compare it to my proposal. The descriptor backup in the "Wallet Payload" of my proposal seems to have some overlap with the BIP proposed here. If there is too much overlap I may reconsider progressing with my proposal.

As mentioned, my proposal is very much a work in progress but the wallet payload proposal can be found here:

https://gist.github.com/KeysSoze/7109a7f0455897b1930f851bde6337e3

Maybe jump to the test vector section to see what a basic backup of a descriptor and some meta data would look like prior to encryption.

https://gist.github.com/KeysSoze/7109a7f0455897b1930f851bde6337e3#test-vectors

As my proposal is designed to be modular and extensible the encryption envelopes may be extended to offer Multiparty Encryption and Authentication. See:

https://gist.github.com/KeysSoze/7109a7f0455897b1930f851bde6337e3#user-content-Expanding_the_Security_Model

I have already started documenting an encryption envelope that uses AES-256-GCM and password protection:

https://gist.github.com/KeysSoze/866d009ccd082edf6802df240154b20d

I have not written a reference implementation yet but there are well established python and Rust libraries for CBOR and COSE that should make implementing the BIPs relatively simple.

pythcoiner · 2025-09-13T10:05:44Z

Hi @pythcoiner,

By coincidence, two weeks ago I started working on a proposal for a "Standard Encrypted Wallet Payload" to be placed inside an "Encrypted Envelope". The "Wallet Payload" contains descriptors and metadata but can also act as a full wallet backup including transactions, UTXOs and addresses. The proposal is very much a work in progress.

Hi @KeysSoze, this work seems more related/parallel to the wallet_backup specs I've work on few month ago.

But I've adopted a slightly different approach by simply using JSON.

FYI we already implemented this wallet backup format in Liana wallet and I plan to work on a BIP proposal relatively soon.

jp1ac4 · 2025-09-15T12:01:03Z

bip-encrypted-backup.md

+
+### Secret generation
+
+- Let $p_1, p_2, \dots, p_n$, be the public keys in the descriptor/wallet policy, in increasing lexicographical order


We might like to use a subset of the public keys in some cases, e.g. if a Taproot descriptor contains an unspendable internal key that is commonly used across multiple descriptors.
cc @bigspider @darosior

right, we also need to specify that BIP0341 NUMS MUST be sorted out

Ideally, for wallet policies, in the long term we might want to introduce a placeholder for a deterministically derived NUMS key, as discussed for example here. So there wouldn't be any xpub at all. But that's not currently specified in BIP-388.

Explicitly excluding all the pubkeys with x coordinate 50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0 seems appropriate and should be forward-compatible with variations of this scheme.

It might be worth mentioning that one could choose just a subset of it is not intended for some of these keys to be able to recover from the backup. The caveat is that it becomes application-specific which of those keys should be able to recover. So if that's mentioned, this should be discussed a bit (for example by adding a recommendation to clearly specify the details in the documentation of the application).

what i'm actually wondering: is there any constructions that have an unspendable key NOT using the BIP341 NUMS?
@hugohn @ben-kaufman @Rob1Ham

Is there some Lightning constructions using unspendable keys?

For the record:

Liana uses BIP0341 NUMS as internal key: https://github.com/wizardsardine/liana/blob/fa342fb9a361e86ef7021ad588ca5ffdf3e12368/liana/src/descriptors/analysis.rs#L413

Nunchunk uses BIP0341 NUMS as internal key: https://github.com/nunchuk-io/libnunchuk/blob/4b6ddb20625d50e8095cb5b8235e4a139581975b/src/descriptor.cpp#L689

Bitcoin-keeper & Anchor watch do not yet support taproot

The caveat is that it becomes application-specific which of those keys should be able to recover. So if that's mentioned, this should be discussed a bit (for example by adding a recommendation to clearly specify the details in the documentation of the application).

I'm quite sure there will be usescases where the user can disable some keys

If encryption tooling adds an option to you strip specific public keys (in addition to the standard NUMS point), then on the decryption side those keys simply fail to decrypt, which seems fine.

Sjors · 2026-01-09T08:38:21Z

The PR is still draft. Are there things you're still working on?

What's the bip.diff file about? Accidentally committed?

Gathered open issues from the inlines threads:

replace BEB with BIP_XXXX once assigned Bip draft: Bitcoin Encrypted Backup #1951 (comment) (and document Liana compatible format)
the VARIANT stuff is confusing

Nit: there's quite a bit of trailing whitespace (which my editor then automatically tries to fix)

Maybe this could replace VARIANT:

#### Content

`CONTENT` is a variable length field defining the type of `PLAINTEXT` being encrypted,
it follows this format:

`TYPE` (`LENGTH`) `DATA`

`TYPE`: 1-byte unsigned integer identifying how to interpret `DATA`.

| Value  | Definition                             |
|:-------|:---------------------------------------|
| 0x00   | Reserved                               |
| 0x01   | BIP Number (big-endian uint16)         |
| 0x02   | Vendor-Specific Opaque Tag             |

`LENGTH`: variable-length integer representing the length of `DATA` in bytes.

For all `TYPE` values except `0x01`, `LENGTH` MUST be present.

`DATA`: variable-length field whose encoding depends on `TYPE`.

For `TYPE` values defined above:
- 0x00: parsers MUST reject the payload.
- 0x01: `LENGTH` MUST be omitted and `DATA` is a 2-byte big-endian unsigned integer representing the BIP number that defines it.
- 0x02: `DATA` MUST be `LENGTH` bytes of opaque, vendor-specific data.

For all `TYPE` values except `0x01`, parsers MUST reject `CONTENT` if `LENGTH` exceeds the remaining payload bytes.

Parsers MUST skip unknown `TYPE` values less than `0x80`, by consuming `LENGTH` bytes of `DATA`.

For unknown `TYPE` values greater than or equal to `0x80`, it MUST stop parsing `CONTENT`.

It might add one extra byte for the BIP case, but that's negligible compared to the length of a typical descriptor. And it reduces complexity.

The TYPE >= 0x80 TYPE rule means we're not stuck with the current TLV encoding. And it has a nice upgrade property: you can still encode backward compatible stuff at the start.

Let's also add quick section to encourage base64 encoding:

### Text Representation

Implementations SHOULD encode and decode the backup using Base64 (RFC 4648).[^psbt-base64]

[^psbt-base64]: **Why Base64?**  
   PSBT (BIP174) is commonly exchanged as a Base64 string, so wallet software likely already supports this representation.

(the footnote format is the same as in BIP3, I think we should use it for all rationale bits)

Sjors · 2026-01-09T09:03:40Z

bip-encrypted-backup.md

+2. **Online redundancy carries privacy risk.**  
+   USB drives, phones, and cloud storage solve the length problem but expose your
+   wallet structure. Plaintext descriptors leak your pubkeys and script details.
+   Cloud encryption doesn't help against subpoenas or provider breaches, and each


Let's not trigger a debate about cloud encryption schemes, maybe say:

Cloud storage is often unencrypted, and even cloud encryption could be compromised, depending on (often opaque) implementation details. Its security also reduces to that of the weakest device with cloud access. Each copy increases the attack surface.

Sjors · 2026-01-09T09:06:48Z

bip-encrypted-backup.md

+   Cloud encryption doesn't help against subpoenas or provider breaches, and each
+   copy increases attack surface.  
+
+These constraints lead to an acute need for an **encrypted**, and


"acute"? It's been years :-)

This BIP therefore proposes an encrypted, and compact backup format that:

Sjors · 2026-01-09T09:14:47Z

bip-encrypted-backup.md

+keys, explicitly exclude any public keys with x coordinate
+`50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0` (the BIP341 NUMS
+point, used as a taproot internal key in some applications). Additionally, exclude any
+other publicly known keys. In some cases, it may be possible to exclude certain keys


Let's move this to a new paragraph:

Applications that exclude additional keys SHOULD document this, although decryption using these keys will simply fail. This does not affect decryption with the remaining keys.

Sjors · 2026-01-09T09:16:49Z

bip-encrypted-backup.md

+
+### Key Normalization
+
+Before computing the encryption secret, all public keys in the descriptor/wallet policy MUST be normalized to **33-byte compressed public key format** (SEC format with 0x02 or 0x03 prefix).


Why not normalise to x-only keys? 32 bytes is a nice size.

In any case, it's good to add a footnote to explain this choice.

yeah if we're gonna "break" things from what we have actually in Liana, I'm happy with x-only also

Sjors · 2026-01-09T09:21:49Z

@murchandamus or other editor: I think this has progressed enough to be BIP number worthy. It would make it easier to generate stable test vectors.

Sjors · 2026-01-09T10:38:08Z

bip-encrypted-backup.md

+defined in `ENCRYPTION` where `PAYLOAD` is encoded following this format:
+
+`CONTENT` `PLAINTEXT`
+


Let's introduce this here, and not repeat it:

#### Integer Encodings All variable-length integers are encoded as [compact size](https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer).

Sjors · 2026-01-09T11:17:50Z

bip-encrypted-backup.md

+
+See [keys_types.json](./bip-encrypted-backup/test_vectors/keys_types.json) for normalization test vectors.
+
+### AES-GCM Encryption


Above you write:

The format uses AES-GCM-256 with a 96‑bit random nonce and a 128‑bit
authentication tag to provide confidentiality and integrity.

But this is a better place to specify that. I think it's good that BIP picks one variant, which allows folks to use a stripped down implementation if needed.

pythcoiner · 2026-01-09T13:00:04Z

@Sjors thanks for the comments, will address during the week end or next week.

The PR is still draft. Are there things you're still working on?

I'm working on another BIP draft for the payload of a wallet backup, i'd like to undraft them together, as they are quite related: the payload is expected to be encrypted with this spec...

In the meantime, I've "played" with a C implementation of this BIP draft, I wanted to check how hard it should be to implement in bitcoin core and I figure out something: it seems there is actually no dependency in core for AES-GCM-256, while there is already usage of CHACHA20 so i'm wondering if we should not use CHACHA20 as default encryption algo? (I'll cross-post to delving)

Sjors · 2026-01-09T13:30:30Z

@pythcoiner using AEAD_CHACHA20_POLY1305 is an interesting idea! Would make it very easy in Bitcoin Core, and perfectly doable in other projects since these are standard components. Good idea to ask on Delving.

In theory we don't need the Poly1305 part, since we're not worried about man-in-the-middle attacks on the backup, but I suspect any library with ChaCha20 will also have Poly1305.

C implementation of this BIP draft

For Bitcoin Core you can use c++, no need to torture yourself. But if it also works in C that makes it easier for hardware wallets to have low level support - not sure if they needed, but still. You could also try with embedded Rust and MicroPython.

Perhaps an extension of the protocol could have hardware wallet sign off on the descriptor / policy, by appending CONTENT with e.g. an HMAC field.

pythcoiner · 2026-01-10T07:56:59Z

What's the bip.diff file about? Accidentally committed?

yes, I've dropped it

pythcoiner · 2026-01-10T08:45:17Z

no need to torture yourself

not felt the torture part 😄

the idea was more, all languages can bind to C, it's not always the case for c++ (or at least less easy) and maybe it worth to have a single implem to maintain

pythcoiner marked this pull request as draft September 4, 2025 06:47

pythcoiner force-pushed the encrypted_descriptor branch from 2a6e241 to d9d02ff Compare September 4, 2025 07:02

Sjors reviewed Sep 4, 2025

View reviewed changes

jonatack added the New BIP label Sep 4, 2025

qlrd mentioned this pull request Sep 4, 2025

Tópicos Setembro saopaulobitdevs/saopaulobitdevs.org#63

Closed

pythcoiner force-pushed the encrypted_descriptor branch 7 times, most recently from 1e4ca34 to 3b6b6ad Compare September 5, 2025 06:30

epcgrs mentioned this pull request Sep 7, 2025

Setembro/2025 poabitdevs/poabitdevs.org#10

Closed

pythcoiner mentioned this pull request Sep 8, 2025

[WIP] Encrypted backup wizardsardine/liana#1807

Draft

7 tasks

torkelrogstad reviewed Sep 8, 2025

View reviewed changes

bip-encrypted-backup.md Outdated Show resolved Hide resolved

PeterMcBTC mentioned this pull request Sep 11, 2025

Create encrypted_descriptor.md proto-at-block/bitkey#6

Open

douglaz mentioned this pull request Sep 11, 2025

Consider supporting the new descriptors-focused encrypted format douglaz/cyberkrill#95

Open

PeterMcBTC mentioned this pull request Sep 12, 2025

Create EncryptedMultisigDescriptor.java sparrowwallet/sparrow#1788

Open

pythcoiner mentioned this pull request Sep 12, 2025

move content metadata to the encrypted payload pythcoiner/bitcoin-encrypted-backup#5

Merged

pythcoiner force-pushed the encrypted_descriptor branch 4 times, most recently from ab0d14d to 2ce692d Compare September 13, 2025 09:44

This comment was marked as spam.

Sign in to view

jp1ac4 reviewed Sep 15, 2025

View reviewed changes

BenWestgate mentioned this pull request Oct 13, 2025

Isn't SSSS each seed at 2-of-2 with Codex32 or SLIP39 and encrypting the descriptor better than this? mflaxman/blind-xpub#8

Closed

pythcoiner force-pushed the encrypted_descriptor branch 4 times, most recently from adc73bb to bfdf6f7 Compare December 2, 2025 13:20

Sjors reviewed Jan 9, 2026

View reviewed changes

bip encrypted_backup

ab5d450

pythcoiner force-pushed the encrypted_descriptor branch from bfdf6f7 to ab5d450 Compare January 10, 2026 07:56


		### Secret generation

		- Let $p_1, p_2, \dots, p_n$, be the public keys in the descriptor/wallet policy, in increasing lexicographical order


		### Key Normalization

		Before computing the encryption secret, all public keys in the descriptor/wallet policy MUST be normalized to 33-byte compressed public key format (SEC format with 0x02 or 0x03 prefix).

		defined in `ENCRYPTION` where `PAYLOAD` is encoded following this format:

		`CONTENT` `PLAINTEXT`


		See [keys_types.json](./bip-encrypted-backup/test_vectors/keys_types.json) for normalization test vectors.

		### AES-GCM Encryption

Bip draft: Bitcoin Encrypted Backup #1951

Are you sure you want to change the base?

Bip draft: Bitcoin Encrypted Backup #1951

Uh oh!

Conversation

pythcoiner commented Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pythcoiner commented Sep 4, 2025

Uh oh!

Sjors commented Sep 4, 2025

Uh oh!

shocknet-justin commented Sep 4, 2025

Uh oh!

Sjors commented Sep 5, 2025

Uh oh!

pythcoiner commented Sep 5, 2025

Uh oh!

Uh oh!

KeysSoze commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pythcoiner commented Sep 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as spam.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bigspider Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sjors commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Sjors Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sjors Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sjors Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sjors commented Jan 9, 2026

Uh oh!

Sjors Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sjors Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

pythcoiner commented Sep 4, 2025 •

edited

Loading

KeysSoze commented Sep 9, 2025 •

edited

Loading

pythcoiner commented Sep 13, 2025 •

edited

Loading

bigspider Sep 16, 2025 •

edited

Loading

Sjors commented Jan 9, 2026 •

edited

Loading

Sjors Jan 9, 2026 •

edited

Loading

Sjors Jan 9, 2026 •

edited

Loading

Sjors Jan 9, 2026 •

edited

Loading

Sjors Jan 9, 2026 •

edited

Loading

Sjors Jan 9, 2026 •

edited

Loading