Edge branch

README.md

@@ -183,7 +183,9 @@ git clone --recursive https://github.com/Coldcard/firmware.git
 cd firmware
 
 # Apply address patch
-git apply unix/linux_addr.patch
+# if unix/linux_addr.patch exists use below command
+# not needed in current revision
+# git apply unix/linux_addr.patch
 
 #  * below is needed for ubuntu 24.04
 pushd external/micropython

cli/signit.py

@@ -319,13 +319,14 @@ def doit(keydir, outfn=None, build_dir=None, high_water=False,
                     pubkey_num=pubkey_num,
                     timestamp=timestamp(backdate) )
 
-    assert FW_MIN_LENGTH <= hdr.firmware_length <= FW_MAX_LENGTH, hdr.firmware_length
 
     if hw_compat & MK_3_OK:
         # actual file length limited by size of SPI flash area reserved to txn data/uploads
+        assert FW_MIN_LENGTH <= hdr.firmware_length <= FW_MAX_LENGTH, hdr.firmware_length
         USB_MAX_LEN = (786432-128)
     else:
-        # new value for Mk4: limited only by final binary size, not SPI flash
+        # new value for Mk4 and later: limited only by final binary size, not SPI flash
+        assert FW_MIN_LENGTH <= hdr.firmware_length <= FW_MAX_LENGTH_MK4, hdr.firmware_length
         USB_MAX_LEN = 1472 * 1024
 
     assert hdr.firmware_length <= USB_MAX_LEN, \

docs/bip-21-extensions.md

@@ -0,0 +1,15 @@
+## Multisig Ownership address check: "wallet"
+
+If the name of the multisig wallet related to an address is provided, address search
+can be greatly accelerated. Just provide `wallet=name` parameter in a standard
+[BIP-21](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) URL
+shown in QR code or NFC record. If omitted, search will continue across 
+all multisig wallets known by COLDCARD.
+
+### Examples
+
+```
+tb1q4d67p7stxml3kdudrgkg5mgaxsrgzcqzjrrj4gg62nxtvnsnvqjsxjkej0?wallet=goldmine
+
+bitcoin:mtHSVByP9EYZmB26jASDdPVm19gvpecb5R?label=coldcard_purchase&amount=50&wallet=Haystack%20Four
+```

docs/generic-wallet-export.md

@@ -57,7 +57,7 @@ to be the first (non-change) receive address for the wallet.
 segregate funds into sub-wallets. Don't assume it's zero.
 
 3. When making your PSBT files to spend these amounts, remember that the XFP of the master
-(`0F056943` in this example) is is the root of the subkey paths found in the file, and 
+(`0F056943` in this example) is the root of the subkey paths found in the file, and 
 you must include the full derivation path from master. So based on this example,
 to spend a UTXO on `tb1qc58ys2dphtphg6yuugdf3d0kufmk0tye044g3l`, the input section
 of your PSBT would need to specify `(m=0F056943)/84'/1'/123'/0/0`.

docs/key-teleport.md

@@ -0,0 +1,224 @@
+
+# Key Teleport
+
+Purpose: Send a small quantity of very secret data between two COLDCARD Q systems, with
+no risk of anything in the middle learning the secret.
+
+Method: ECDH and AES-256-CTR plus an extra wrapping layer, transmitted over a mixture of
+NFC, passive websites, and QR/BBQr codes.
+
+# Protocol Overview
+
+## Steps
+
+- Receiver picks an EC keypair, stores it in settings, and publishes the pubkey via a QR/NFC
+- The pubkey is encrypted by a short 8-digit numeric code, which should be
+  sent by a different channel.
+- Sender gets QR and numeric code, picks own keypair, and does ECDH to arrive at a
+  shared session key
+- Sender picks a human-readable secret which is independent of anything else (P key)
+- The secret data (perhaps a seed phrase, XPRV, secure note, full backup, etc) is
+  AES-256-CTR encrypted with P key, then encrypted + MAC added with session key
+- Data packet is sent to receiver (via BBQr), who can reconstruct the session key via ECDH
+- Prompt user for the P key to finish decoding
+- Decoded secret value is saved to Seed Vault or secure notes as appropriate
+- Receiver destroys EC keypair used in transfer
+
+### When used for PSBT Multisig
+
+- No action required on receiver
+- Sender uses the pubkey derived from pre-shared XPUB involved in the multisig wallet.
+- Same steps, but drops immediately into signing process when decoded correctly
+
+## Notes and Limitations
+
+- max 4k (after encoding) of data is possible due to HTTP limitations
+- all transfers are "data typed" and decode only on COLDCARD
+- Q model is required due to the use of QR codes to ultimately get data into the COLDCARD
+
+
+# Details
+
+## Data Type Codes
+
+The first byte encodes what the package contents (under all the encryption).
+
+- `s` - 12/18/24 words/raw master/xprv - 17-72 bytes follow, encoded in an internal format
+- `x` - XPRV mode, full details - 4 bytes (XPRV) + base58 *decoded* binary-XPRV follows
+- `n` - one or many notes export (JSON array)
+- `v` - seed vault export (JSON: one secret key but includes name, source of key)
+- `p` - binary PSBT to be signed, perhaps multisig but not required.
+- `b` - complete system backup file (text lines, internal format)
+
+## QR details
+
+BBQr is always used for the QR's involved in this process, even if
+they are short enough for a normal QR code. Because the BBQr is
+being generated by the COLDCARD embedded firmware, it will not be
+compressed and will always be Base32 encoded.
+
+New type codes for BBQr are defined for the purposes of this application:
+
+- `R` contains `(pubkey)` ... begins the process from receiver; compressed pubkey is 33 bytes
+- `S` contains `(pubkey)(data)` ... data from sender; first 33 bytes are sender's pubkey
+- `E` for Multisig PSBT: `(randint)(data)` ... randint (4 byte nonce) indicates which 
+  derived subkey from pre-shared xpub associated with receiver
+
+All the data is encrypted with the exception randint. Keep in mind
+this is a nonce value picked uniquely for each transfer. The
+receiver's pubkey is only weakly encrypted by the 8-digit numeric
+password, but is also a nonce effectively.
+
+### PSBT Key Selection
+
+When sending PSBT data, a nonce is picked at random by the sender
+in range: `0..(2^28)`
+
+This nonce is called `randint`. The receiver's pubkey will be
+
+    .../20250317/(randint)
+
+where `...` is the derivation used in the multisig wallet for the co-signer who will
+receive the package. The sender's keypair has the same sub key path assuming all
+co-signers have same derivation path from root (not required).
+
+Because both the sender and receiver already have each other's XPUB they can derive
+the appropriate pubkeys (and privkey for their side) without communicating 
+more than `randint`. The sending COLDCARD will pick a new random value each time.
+
+When receiving a multisig PSBT encrypted this way, the receiver does not need
+to do any setup (nor numeric password) and can receive a QR code at any time.
+This works because the shared multisig wallet is already setup. Receiver will
+take the nonce value (randint) and seach all pre-defined multisig wallets for
+any pubkey that can decrypt the package successfully (based on checksum inside
+first layer of ECDH encryption).
+
+The next layer of encryption (paranoid password) is unchanged.
+
+## Encryption Details
+
+AES-256-CTR is used exclusively. Session key is picked via ECDH with final
+key value being the SHA256 over 64 bytes of coordinate X (concat) Y.
+
+While ECDH is enough to assure privacy from men in the middle, we
+add an additional layer of encryption. We call this the "paranoid key" internally
+and in the UX it is called "Teleport Password".
+
+The user sees a random 8-character password, generated as a random 40-bit value, but
+shown in Base32 (8 chars) for the human to enter. We apply PBKDF2-SHA512 with
+an iteration count of 5000 to stretch that to 512 bits, of which we use half.
+The session key is used as the key for the KDF, and the entered value as salt.
+
+- ECDH arrives at session key
+- decrypt (AES-256-CTR) the binary body of message
+- verify checksum:
+    - final 2 bytes should be `== SHA256(decrypted body[0:-2])[-2:]`
+    - if not, corruption, truncation, or wrong keys
+- if that decryption is correct, then prompt user for the paranoid key (8 chars)
+- stretch that value using session key and 5000 iterations of PBKDF2-SHA512
+- use upper 256 bits and run AES-256-CTR again
+- same checksum of 2 bytes of SHA256 are found inside after decryption
+
+Encryption adds 4 bytes of overhead because of these MAC values, 
+but should catch truncation and bitrot. There are no other
+protections against truncation as length data is not transmitted.
+
+# Receiver Password
+
+When the teleport process is started, the receiver shares his pubkey
+as QR. However, we also show an 8-digit numeric password. The
+purpose of this is force the receiver to share this separately from
+the pubkey QR on another channel. The code is randomly picked, but
+only represents about 26 bits of entropy and is stretched with
+a single round of SHA256 before being used as a AES-256-CTR key
+to decrypt the pubkey. No checksum verifies correct
+decryption, so any code is accepted, and will with near-50% odds,
+decrypt to a valid pubkey.
+
+When the sender is given the receiver's pubkey via QR code, it
+prompts for the numeric code and uses it to decrypt the pubkey.
+Thus a MiTM who injects their pubkey will be detected and blocked.
+
+The "paranoid key" serves the same role in the other direction but
+it is Base32 character set, so it will not look similar or be
+confusing as to its purpose.
+
+# Web Component
+
+In order to "teleport" the contents of a QR code over NFC, we will
+publish a static website directly from an open Github repository.
+The single-page website contains javascript code which looks at the
+"hash" part of the incoming URL (`window.location.hash`) and if it
+meets the requirements, renders a large QR. The QR data must look like
+a correctly-encoded BBQr with one of the 3 type-codes above (`R` `S` or `E`).
+Otherwise the website could render any QR, which we don't want to
+support.
+
+The page will offer "copy to clipboard" features for the data inside
+the QR as a URL (ie. same URL as shown) and as an image and of course,
+the COLDCARD Q can scan from the web browser screen itself.
+
+When the BBQr data is larger than comfortable for a single QR, the
+website can split into a multi-frame BBQr. The website can
+do this without understanding the contents of the BBQr data (all
+of which is encrypted). Download options will be provided for
+single-frame QR, animated PNG, and "stacked BBQr" (a single tall
+PNG with each QR frame stacked).
+
+On the COLDCARD side, when NFC is tapped, it will offer a long URL
+to this site with the data to be transferred "after the hash".  This
+is optional since the QR can be shown on the Q itself, and would
+pass the same data.
+
+Since the website is running on Github, Coinkite does not have
+access to IP addresses or other access log details. Because the data for
+teleport is "after the hash" it is never sent to Github's servers
+but remains in the browser only. All JS resources referenced by the
+webpage will have content hashes applied to prevent interference,
+and the site will be served over SSL.
+
+Visit [keyteleport.com](https://keyteleport.com/), or an
+[example small QR](https://keyteleport.com/#B$2R0100VHT2AGUUH7KUZUUSTOWOIWHJX3XM7GA2N4BHQOXDFHXLVHVA7K6ZO)
+and [view source code](https://github.com/coinkite/keyteleport.com).
+
+# UX Details
+
+- When the receive process is started by the user, a pubkey is picked
+  and stored, so that they can come back later (after a power cycle)
+  and make use of the data encoded by the sender. However once a package
+  is decoded successfully, that key is deleted.
+
+- Sender must start by scanning the QR from a receiver. Then can pick what
+  to send, from secure notes to seeds and so on.
+
+- For PSBT multisig, user must pick a single co-signer (who hasn't already
+  signed) and the QR is prepared for that receiver. Because we
+  cannot do arbitary combining, it's best if the next signer continues
+  to teleport the updated PSBT to further signers. In other words,
+  a daisy-chain pattern is prefered to a star pattern. The signer
+  who completes the Mth (of N) signature will be able to finalize
+  the transaction, and ideally with PushTx feature, broadcast it.
+
+# Security Comments
+
+## Such short passwords?
+
+We are using 8-character passwords because we want them to be
+practical to share over non-digital channels such as a voice phone
+call, or hand-written note.
+
+It is very important to remind users that the passwords should be sent
+by a different channel from the QR itself. Best is to call up your
+other party and say the letters to them directly.
+
+## Is it safe to save image of QR to cloud?
+
+Yes, this seems safe. Of course, if you can control it, perhaps not
+a risk to accept... but the QR is encrypted via ECDH using a key
+that is forgotten after the transfer, so forward privacy is protected.
+Also your cloud service (or photo roll, chat app log, etc) will not
+have the 8-character password which is also required unpack the secrets.
+
+The QR codes themselves are fully random and do not reveal the
+identity of your COLDCARD, your on chain funds or anything linked
+to you.

docs/limitations.md

@@ -14,11 +14,12 @@
 # PIN Codes
 
 - 2-2 through 6-6 in size, numeric digits only
-- pin code 999999-999999 is reserved (means 'clear pin')
+- pin code 999999-999999 was reserved (meaning 'clear pin'), but now available again
 
 # Backup Files
 
 - we don't know what day it is, so meta data on files will not have correct date/time
+- release date of the firmware version that made the file is used instead of true date
 - encrypted files produced cannot be changed, and we don't support other tools making them
 
 # Micro SD
@@ -55,14 +56,18 @@
 
 - only one signature will be added per input. However, if needed the partly-signed 
   PSBT can be given again, and the "next" leg will be signed.
-- we do not support PSBT combining or finalizing of transactions involving
-  P2SH signatures (so the combine step must be off-device)
+- finalizing of multisig transactions involving P2SH signatures:
+    * SD/Vdisk signing exports both signed PSBT and finalized txn ready for broadcast (if txn is complete)
+    * QR/NFC outputs finalized txn ready for broadcast if txn is complete otherwise signed PSBT only
+    * USB signing requires `--finalize` parameter (as for standard single signature wallets)
+
 - we can sign for P2SH and P2WSH addresses that represent multisig (M of N) but
   we cannot sign for non-standard scripts because we don't know how to present
   that to the user for approval.
 - during USB "show address" for multisig, we limit subkey paths to
   16 levels deep (including master fingerprint)
-- max of 15 co-signers due to 520 byte script limitation in consensus layer with classic P2SH (same limit applies to segwit even though consensus allows up to 20 co-signers)
+- max of 15 co-signers due to 1650 byte `scriptSig` limitation in policy with classic P2SH (same limit applies to segwit even though consensus allows up to 20 co-signers).
+  note: the consensus layer sets an upper bound of 520 bytes for the length of each stack element
 - (mk3) we have space for up to 8 M-of-3 wallets, or a single M-of-15 wallet. YMMV
 - only a single multisig wallet can be involved in a PSBT; can't sign inputs from two different
     multisig wallets at the same time.
@@ -74,6 +79,7 @@
 - multisig wallet `name` can only contain printable ASCII characters `range(32, 127)`
 
 ### BIP-67
+
 - importing multisig from PSBT can ONLY create `sortedmulti(...)` multisig according to BIP-67, DO NOT use with `multi(...)`
 - creating airgapped multisig using COLDCARD as coordinator always produces `sortedmulti(...)` multisig according to BIP-67
 - COLDCARD import/export [format](https://coldcard.com/docs/multisig/#configuration-text-file-for-multisig) only supports `sortedmulti(...)` multisig according to BIP-67. To import multisig wallet with `multi(...)` use descriptor import [format](https://github.com/bitcoin/bips/blob/master/bip-0383.mediawiki)
@@ -128,12 +134,17 @@ We will summarize transaction outputs as "change" back into same wallet, however
     - `p2wsh-p2sh`: _redeemScript_ (which is: `0x00 + 0x20 + sha256(witnessScript)`), and
       _witnessScript_ (which contains the multisig script)
     - `p2wsh`: only _witnessScript_ (which contains the actual multisig script)
-
+    - `p2tr`(keypath singlesig): no _redeemScript_, no _witnessScript_ and output key MUST commit to an unspendable script path as follows `Q = P + int(hashTapTweak(bytes(P)))G`
+    - `p2tr`(scriptpath multisig): _taproot_merkle_root_ and _leaf_script_ more info in docs/taproot.md
 
 # Derivation Paths
 
 - key derivatation paths must be 12 or less in depth (`MAX_PATH_DEPTH`)
 
+# Pay-to-Pubkey
+
+- although we have some code for "pay to pubkey" (P2PK not P2PKH), it is untested
+  and unused since this style of payment address is obsolete and largely unused today
 
 # NFC Feature
 
@@ -198,3 +209,16 @@ We will summarize transaction outputs as "change" back into same wallet, however
 - if you have an XFP collision between multiple wallets in SeedVault (ie. two wallets
   with same descriptors, but different seeds) you will get false negatives
 
+# Spending Policy
+
+- (Cosign mode) only 12 or 24 word seeds (not XPRV) are accepted for "key C"
+- velocity limit:
+    - based on a max magnitude per txn, and a required minimum block height
+      gap, based on previous `nLockTime` value in last-signed PSBT.
+    - if you sign a transaction, but never broadcast it, you will still have to wait out 
+      the velocity policy.
+    - PSBT creator must put in `nLockTime` block heights (most already do to avoid fee sniping)
+- maximum of 25 whitelisted addresses can be stored
+- Web2FA: any number of mobile devices can be enrolled, but all will have the same shared secret
+- any warning from the PSBT, such as huge fees, will cause the transaction to be rejected
+