This PR proposes a standardized process for setting up Bitcoin multisig wallets securely.
Original mailing list discussion: https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2021-February/018385.html Original draft PR: https://github.com/nunchuk-io/bips/pull/1
113+===Encryption===
114+
115+====The Token====
116+We define three modes of encryption.
117+
118+# <tt>NO_ENCRYPTION</tt> : the <tt>TOKEN</tt> is set to <tt>0</tt>. Encryption is disabled.
0 the byte, not 0 the digit (ascii byte 48).
I raised some objections to this BIP on the bitcoin-dev email list, duplicating my comments here as well.
–
Hi Hugo,
I appreciate the effort you and everyone else is making to improve multisig in bitcoin!
I like that this BIP gets rid of SLIP132 version bytes, as those have been de-facto deprecated in favor of output descriptors for some time. Having a standard for how to communicate descriptor records (BSMS 1.0) also seems like a nice positive.
The most commonly raised issues from the 10x security guide are about how to properly verify that all hardware wallets are participants in the user’s multisig quorum (and with the correct m-of-n). This shows up in two big ways:
Unfortunately, this BIP does not improve either of these issues, while adding considerable complexity.
The proposed use of an output descriptor checksum has an obvious 40-bit MITM collision attack. A compromised Coordinator could trick a Signer into displaying an attacker’s receive address, despite a correctly functioning Signers and the user properly validating the checksum (github link).
Using a checksum with much higher entropy would reduce xpub validation to O(n) and create a very nice UX for signers. This would be a huge win for multisig! Instead, the recommended solution from the BIP is to validate all the key records manually, which is how multisig is currently done and what we desperately want to move away from. With a proper checksum, there’s no reason for a user to ever see an xpub.
Users should not be shown a checksum and asked to validate it in meatspace (across Signers) if an attacker’s address could still be substituted! Validating a single address across devices does solve this problem, but if you’re going to validate an address there’s no reason to display the checksum at all. However, validating an address is confusing to non-experts:
If creating a new checksum standard for the descriptor record is undesirable, we could use a child address (from an unhardened BIP32 path) and encode that in some way for end-users to verify it matches across all Signers. It would be strongly preferable for the encoding to be an unambiguously different format from a bitcoin address / BIP39 seed phrase, so that it’s clear it’s just a wallet ID. One non-ideal but simple solution is to use a hash function (i.e. dsha256) to calculate the digest of the child address, and display this in hexadecimal format. While hexadecimal is non-ideal for manual verification, it is already trivial for any bitcoin library to perform these steps.
The current BIP states:
“If all checks pass, the Signer must persist the descriptor record in its storage.”
While persistence has a lot of benefits, it is not a feature of the most sold multisig hardware wallet: Trezor. A simple solution here is to have each Signer sign the entire descriptor record at the end of round 2, not just its own key record in round 1. Then the data can be stored anywhere (including on the Signer itself) and played back to each Signer for validation when needed. The end-user would have no idea this was happening, but the device could refuse to display information it hasn’t fully validated (or at least add a warning message). Even a device with persistent storage would be better served using a signature, so that an evil maid couldn’t tamper with the device (say in the no-encryption case for simplicity).
This existing vulnerability in stateless wallets is particularly bad for hosted multisig services like Casa/Unchained, where the service might control m-1 keys. It’s far easier for a hosted service to potentially trick non-expert users into displaying an attacker’s receive address on their stateless Signer.
For example, assume the user is doing 2-of-3 multisig, where the Coordinator (service) controls 1 key. Here is how the Coordinator could trick their end-users:
If stateless Signer 1 required a signature to be replayed at step 3, stateless Signer 1 would refuse to display malicious receive address X (or at a minimum warn the end-user that it did not have enough info to properly validate the address).
This is also a concern for self-hosted multisig, I just used the hosted services as the best example.
It’s also not just Trezor that is stateless. For example, I wrote a simple CLI software multisig wallet as part of the buidl library to be used mostly for emergency recovery. At 800 lines of code, it’s too simple/minimal to touch the file system.
While unrelated, the use of BIP39 words for session tokens seems like a big mistake, as end-users have learned over years that BIP39 words are for private key material. A small percent of users may backup their token BIP39 mnemonic and not their seed phrase BIP39 mnemonic! My suggestion is to just stick with the other two Token options: decimal and hex.
The main purpose/benefit of the BIP seems to be the encryption protocol. I wouldn’t have strong objections if the BIP were simply renamed Bitcoin Multisig Encryption, as that more accurately reflects what it does. That said, I think this BIP is missing out on a real opportunity to improve security in setting up a multisig scheme, and if adopted in the current form will negatively impact multisig adoption.
I can’t support this BIP in the current form, but I’d be happy to submit a PR if it’s helpful.
Best,
Michael https://btcguide.github.io/
I think there are serious issues with this PR in its current form:
For details, see here.
@mflaxman thanks, my response here: https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2021-April/018776.html
If possible, please try to keep the comments in one location.
For those reading this github thread, besides @hugohn ’s linked response on the ML, this has also been discussed in the original PR here, here, here, and here.
All proposed solutions have been implemented, except for a larger checksum, which requires a proposed change to the descriptor language (not this PR)
Hugo, referencing the bitcoin-dev posts I agree with making Signers display the first receive address a mandatory part of the Round 2 process to mitigate the checksum collision attack described by @mflaxman. In addition, it’s a familiar format and users generally already know how to find the first address in their Coordinators. Once the setup is complete, it’s also normally the first use of the new wallet (to receive funds at that address). For simplicity, I suggest only the first address should be displayed however.
Thanks @craigraw. Yes, I’m leaning in this direction as well.
85+* For each key record, the Coordinator extracts the <tt>MAC</tt> from the data, sets <tt>IV</tt> to the first 16 bytes of the <tt>MAC</tt>, then decrypts the ciphertext using the <tt>ENCRYPTION_KEY</tt> and <tt>IV</tt>.
86+* The Coordinator verifies that the included <tt>MAC</tt> is valid given the plaintext.
87+* The Coordinator verifies that the key records have compatible specification versions.
88+* The Coordinator verifies that the included <tt>SIG</tt> is valid given the <tt>KEY</tt>.
89+* If all key records look good, the Coordinator fills in all necessary information to generate a descriptor record.
90+* The first line in the descriptor record must be the specification version (<tt>BSMS 1.0</tt> as of this writing). The second line must be a comma-separated list of accepted derivation paths that the Signers can use to generate addresses from the included XPUBs. The paths must start with <tt>/</tt> and use non-hardened derivation. For example, <tt>/0/*</tt> and <tt>/1/*</tt> are some common paths. If there are no restrictions, it must say <tt>No path restrictions</tt>. The third line must be the descriptor string plus a <tt>CHECKSUM</tt>, all in one line. The <tt>CHECKSUM</tt> has [https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md#checksums BECH32 encoding].
A minor note: while the third line is syntactically a valid descriptor as per Bitcoin Core, it isn’t semantically. For example, wsh(sortedmulti(2,keyA/*,keyB/*))#checksum describes the list [wsh(sortedmulti(2,keyA/0,keyB/0)), wsh(sortedmulti(2,keyA/1,keyB/1))], wsh(sortedmulti(2,keyA/2,keyB/2)), ...], which is very different from what it represents in the context of BSMS. Therefore, calling that a descriptor might generate confusion, as it has already happened in the discussion.
The idea of separating the valid derivation paths from the output descriptors is great, as it works well for any multisig scenario, and as far as I understand it seamlessly generalizes to miniscript policies).
Therefore, I think it might be worth finding a new term (for example descriptor template; or wallet descriptor) and have a short paragraph in the introduction to explain how the descriptor template is expanded with the possible derivation paths to obtain the full list of output script descriptors, which would harmonize the naming with Core.
Such descriptor template, as it currently stands, would be exactly like a descriptor, except it redefines the meaning of the * symbol.
I don’t have a strong opinion on this, since it’s just a very small difference in terminology. Calling that line a “descriptor template” is fine with me. But IMHO calling it just a “descriptor” is not wrong either, syntactically and semantically.
Such descriptor template, as it currently stands, would be exactly like a descriptor, except it redefines the meaning of the
*symbol.
I don’t think we are redefining the meaning of /*. /* simply means that the Signers are entering a contract that accepts all non-hardened keys/addresses under the XPUBs being submitted.
An address generated from /0/* belongs to the address space of /* as well.
One can think of /0/* and /1/* as conventions that parties agree among themselves to reduce the usable address space within /*.
An address generated from
/0/*belongs to the address space of/*as well.One can think of
/0/*and/1/*as conventions that parties agree among themselves to reduce the usable address space within/*.
This is not what * means in output descriptors, and the precise reason you want a different term (if not a different symbol altogether).
In hindsight, I would have preferred to have the # symbol in output descriptors for the address index, and reserve * for use cases like yours.
Another option could be to use \** for the descriptor template, which is a standard way of matching all subpaths when describing paths in a filesystem (e.g. in .gitignore), which is a familiar semantics for many people. Moreover, it would be visually different and an invalid descriptor. This is desirable in my opinion, since entering the descriptor template into a descriptor wallet would not find any valid addresses!
This might also address the concerns that @Rspigler and @prusnak voiced multiple times.
An address generated from
/0/*belongs to the address space of/*as well. One can think of/0/*and/1/*as conventions that parties agree among themselves to reduce the usable address space within/*.This is not what
*means in output descriptors
What do you mean? I’m interpreting * here as per defined in https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md:
Optionally followed by a single /* or /*’ final step to denote all (direct) unhardened or hardened children.
/* literally means all unhardened children, of which /0/* and /1/* are subsets.
direct, as in exactly 1 level of derivation. Perhaps that page should be clarified as well, I had the same confusion the first time I read it.
The rationale is: a descriptor wallet needs to give enough information to easily find the described addresses. Therefore, you want a 1-dimensional list you can iterate.
direct, as in exactly 1 level of derivation. Perhaps that page should be clarified as well, I had the same confusion the first time I read it.
I actually missed this. Good point, I stand corrected.
For simplicity, I suggest only the first address should be displayed however.
+1 using the first receive address for validation, as OP_HASH160 is considered collision resistant under bitcoin’s security model. However, this should replace displaying the 40-bit checksum, as there’s no reason for humans to be manually verifying things in meatspace that do not provide real security. Put differently: if you validate the first address on all Signers it doesn’t matter what the checksum is, if you don’t validate the first address on all Signers then a compromised Coordinator can use the checksum to fool you.
My preferred solution would still be a much longer checksum in bitcoin core, but this hackey solution is secure if it’s too hard to get upstream agreement on that.
IYC, I started a draft of an encoding proposal here, but ultimately decided to abandon it because I thought the negatives outweighed the positives.
+1 using the first receive address for validation, as OP_HASH160 is considered collision resistant under bitcoin’s security model.
160 bit hashes are only considered secure for single-sig use. See e.g. BIP-0341 rationale for not allowing p2sh-wrapping: https://github.com/bitcoin/bips/blob/1f0b563738199ca60d32b4ba779797fc97d040fe/bip-0341.mediawiki#cite_note-3 However, whatever security the “first” receive address has is clearly considered sufficient by its owner so it should be good to use for validating the multisig.
+1 using the first receive address for validation, as OP_HASH160 is considered collision resistant under bitcoin’s security model.
160 bit hashes are only considered secure for single-sig use. See e.g. BIP-0341 rationale for not allowing p2sh-wrapping: https://github.com/bitcoin/bips/blob/1f0b563738199ca60d32b4ba779797fc97d040fe/bip-0341.mediawiki#cite_note-3
Bitcoin Optech had a very nice newsletter on this topic: https://bitcoinops.org/en/bech32-sending-support/#address-security
The short summary is that for multi-party multisig it is safer to use native SegWit than wrapped SegWit. In the worst case, you’d still get 128-bit address security, since P2WSH uses the longer hash function SHA256d instead of RIPEMD160. Also worth noting that the theoretical weakness of RIPEMD160 would still likely take an attacker billions of dollars to exploit.
Nevertheless, address security is not really a concern of this spec. Whatever weaknesses exist for Bitcoin addresses, they should be addressed in the Bitcoin protocol, not here.
Updates:
Test vectors to be updated.
Should the descriptor template have a checksum like the descriptor? (I see the checksum verification is now gone even if a descriptor is used)
Can you explain the rationale for expanding to xpubs and public keys? How would that work
Should the descriptor template have a checksum like the descriptor? (I see the checksum verification is now gone even if a descriptor is used)
Now that we mandate the verification of first address, the checksum technically isn’t necessary. Since first address provides stronger integrity check.
The descriptor language also only defines a checksum for a “valid” descriptor. You can still include the checksum in the descriptor string if you really want to, just not the template.
Can you explain the rationale for expanding to xpubs and public keys? How would that work
Just like how it would work in a descriptor that uses public keys instead of XPUBs (a KEY expression in the descriptor language can be either one).
For example, a one-time use multisig wallet that has a single receive address (and no change).
I’ll update the test vectors separately.
53+
54+The Coordinator initiates the multisig setup. The Coordinator determines what type of multisig is used and the exact policy script. If encryption is enabled, the Coordinator also distributes a shared secret or shared secrets to the parties involved for secure communication. The Coordinator gathers information from the Signers to generate a descriptor record. The Coordinator distributes the descriptor record back to the Signers.
55+
56+====Signer====
57+
58+The Signer is any software or hardware that controls the private keys and can sign using those keys. The Signer is a participating member in the multisig. Its responsibilities include providing its key record -- which contains a public key or an Extended Public Key (XPUB) -- to the Coordinator, verifying that its key is included in the descriptor record and persisting the descriptor record in its storage.
<tt>KEY</tt>
69+* If encryption is disabled, the <tt>TOKEN</tt> is set to <tt>0x00</tt>, and all the encryption/decryption steps below can be skipped.
70+
71+=====Signer=====
72+
73+* The Signer initiates the multisig wallet creation session by setting the <tt>TOKEN</tt>. The Signer derives an <tt>ENCRYPTION_KEY</tt> from the <tt>TOKEN</tt>. The Signer can keep the session open until a different value for the <tt>TOKEN</tt> is set.
74+* The Signer generates a key record by prompting the user for a multisig derivation path and retrieves the key at that derivation path. Alternatively, the Signer can choose a path on behalf of the user. If the Signer chooses the path, it should try to avoid reusing keys for different wallets.
<tt>KEY</tt>
83+
84+* The Coordinator gathers key records from all participating Signers. The Coordinator verifies that there are exactly <tt>N</tt> unique key records before the wallet setup session expires.
85+* For each key record, the Coordinator extracts the <tt>MAC</tt> from the data, sets <tt>IV</tt> to the first 16 bytes of the <tt>MAC</tt>, then decrypts the ciphertext using the <tt>ENCRYPTION_KEY</tt> and <tt>IV</tt>.
86+* The Coordinator verifies that the included <tt>MAC</tt> is valid given the plaintext.
87+* The Coordinator verifies that the key records have compatible specification versions.
88+* The Coordinator verifies that the included <tt>SIG</tt> is valid given the <tt>KEY</tt>.
98+* The Signer imports the descriptor record.
99+* The Signer extracts the <tt>MAC</tt> from the data, sets <tt>IV</tt> to the first 16 bytes of the <tt>MAC</tt>, then decrypts the ciphertext using the <tt>ENCRYPTION_KEY</tt> (derived from the open session) and <tt>IV</tt>.
100+* The Signer verifies that the included <tt>MAC</tt> is valid given the plaintext.
101+* The Signer verifies that it can support the included specification version.
102+* The Signer verifies that it can support the descriptor or descriptor template.
103+* The Signer checks that its <tt>KEY</tt> is included in the descriptor, using path and fingerprint information provided. The check must perform an exact match on the <tt>KEY</tt>s and not using shortcuts such as matching fingerprints, which is trivial to spoof.
100+* The Signer verifies that the included <tt>MAC</tt> is valid given the plaintext.
101+* The Signer verifies that it can support the included specification version.
102+* The Signer verifies that it can support the descriptor or descriptor template.
103+* The Signer checks that its <tt>KEY</tt> is included in the descriptor, using path and fingerprint information provided. The check must perform an exact match on the <tt>KEY</tt>s and not using shortcuts such as matching fingerprints, which is trivial to spoof.
104+* The Signer verifies that it is compatible with the derivation path restrictions.
105+* The Signer verifies that the wallet's first address is valid given the descriptor and the path restrictions.
First address is valid given the descriptor
At this point, should the descriptor template have expanded into two descriptors? When a user asks the software/hardware to show the descriptor (for confirmation) does this standard say to provide the template, or the expanded descriptors?
It has to be expanded in order to verify the validity of the first address. I don’t think it needs to be said since there’s no other way to validate.
The template, since path restrictions are shown as well. I’ve clarified in the text.
A couple of updates, most of which are minor text edits / rephrasing to make things clearer. Two notable changes:
Rationale for (2): it doesn’t feel right to limit ourselves to a lower bit security just because of a potential problem with one out of hundreds of possible encodings. The solution here is to go with higher bit security while explicitly disallowing the problematic encoding for such a mode.
I’ll add a Backward Compatibility section separately.
ACK commit abbb76e987cf0ecba43131a5dfcc98771ea6848f, 3ecad81bea81c3be6188139a7318562b9f7797e6, 45bc31d83d31a5c688072ac7e060d16f8513aad9, de79a73b49aae1dc98fd0c05e548f1b7844c3065, 75bb056596b19d1cb5bd440a83ccd579ffb3188a, e82de1d3bb7313e500e75ed17deeb8463f53b305, cf00b456798eedb829f2d247eaf974b9668f5376
This is looking really great. Glad to see the 128-bit extension
178+==QR Codes==
179+For signers that use QR codes to transmit data, key and descriptor records can be converted to QR codes, following [https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-005-ur.md the BCR standard].
180+
181+Also refer to [https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-015-account.md UR Type Definition for BIP44 Accounts] and [https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-010-output-desc.md UR Type Definition for Bitcoin Output Descriptors] for more details.
182+
183+==Compatibility==
@luke-jr BSMS is opt-in so it doesn’t really affect existing multisig wallets (unlike many changes at the Bitcoin protocol layer where everyone has to upgrade). If you already had a multisig wallet, you can continue using it as-is, with the caveat that existing multisig solutions on the market are full of pitfalls. @benma wrote an article on this topic last year: https://benma.github.io/2020/11/05/multisig-xpubs-verification.html. We also discovered a related vulnerability that motivated us to write this standard in the first place. See https://medium.com/nunchuk/the-missing-multisig-standard-5b4092e3ea92.
The stateful nature of the Signer and an interoperable multisig configuration proposed in this spec are to address the problems with existing solutions.
To use BSMS, vendors (such as Coldcard, Trezor, BitBox02, Ledger, Cobo etc.) first have to update their firmware to add support for BSMS. After the users upgrade to the new firmware, they can create new multisig wallets or upgrade their existing ones to use BSMS. But it’s entirely opt-in.
85+* For each key record, the Coordinator extracts the <tt>MAC</tt> from the data, sets <tt>IV</tt> to the first 16 bytes of the <tt>MAC</tt>, then decrypts the ciphertext using the <tt>ENCRYPTION_KEY</tt> and <tt>IV</tt>.
86+* The Coordinator verifies that the included <tt>MAC</tt> is valid given the plaintext.
87+* The Coordinator verifies that the key records have compatible specification versions.
88+* The Coordinator verifies that the included <tt>SIG</tt> is valid given the <tt>KEY</tt>.
89+* If all key records look good, the Coordinator fills in all necessary information to generate a descriptor record.
90+* The first line in the descriptor record must be the specification version (<tt>BSMS 1.0</tt> as of this writing). The second line must be a descriptor or a descriptor template. The third line must be a comma-separated list of derivation path restrictions. The paths must start with <tt>/</tt> and use non-hardened derivation. If there are no template or restrictions, it must say <tt>No path restrictions</tt>. The fourth line must be the wallet's first address. If there are path restrictions, use the first address from the first path restriction.
189+
190+BSMS is opt-in, meaning existing multisig implementations can continue working as-is, with the caveat that they are full of pitfalls. Some of the problems have been described in the [[#Motivation]] section.
191+
192+To comply with this standard, a Signer must be able to persist the descriptor record in its storage.
193+
194+Once a Signer has implemented BSMS, the user can create new multisig wallets using BSMS or migrate existing ones to BSMS.
191+
192+To comply with this standard, a Signer must be able to persist the descriptor record in its storage.
193+
194+Once a Signer has implemented BSMS, the user can create new multisig wallets using BSMS or migrate existing ones to BSMS.
195+
196+Existing multisig wallets should delay upgrading to BSMS until all participating Signers have implemented BSMS.
171+
172+A descriptor template must be accompanied by derivation path restrictions. Signers should expand the template into concrete descriptors by replacing <tt>/**</tt> with the restrictions.
173+
174+For example, the following template and derivation path restrictions:
175+* <tt>wsh(sortedmulti(2,XPUB1/**,XPUB2/**))</tt>
176+* <tt>/0/*,/1/*</tt>
/0/* needed here? It seems that it is better to specify this as 0/*,1/*
/ so that it’s clear that it’s a path, not a number.
Also, I’ve updated my BIP draft for path restrictions (https://github.com/dgpv/bips/blob/bip-path-templates/bip-path-templates.mediawiki, #1025) to use ‘{}’ for ranges, which makes the format more in line with https://github.com/bitcoin/bitcoin/issues/17190 and removes a clash with [] in descriptors.
It describes a format that might be more complex than desired for this particular purpose, but at the same time it is thoroughly specified and it can be made fully unambiguous.
The 0/*,1/* could be specified as {0-1}/* when using the format in my BIP draft (the {0-1}/* would be “partial path template” because it does not start with m/, and the {0,1}/* form is better disallowed, thus the path encoding can be fully unambigous)
Probably shouldn’t put BSMS on hold though.
I fully agree.