Upgrade Firmware
Current Version of Coldcard Firmware
**For Mk4 (our flagship!): ** 2023-09-08T2009-v5.1.4-mk4-coldcard.dfu released Sept 8, 2023.
**For Mk3/Mk2: ** 2023-06-26T1241-v4.1.9-coldcard.dfu released Jun 26, 2023
Find all available downloads here.
Video: How to Upgrade Firmware
Mk4: Version 5.1.4 - Sept 8, 2023#
- New Feature: Batch sign multiple PSBT files.
Advanced/Tools -> File Management -> Batch Sign PSBT
- Enhancement:
Sparrow Wallet
added as an individual export option (same file contents) - Enhancement: change key origin information export format in multisig
addresses.csv
to match BIP-0380 was(m=0F056943)/m/48'/1'/0'/2'/0/0
now[0F056943/48'/1'/0'/2'/0/0]
- Enhancement: Address explorer UX cosmetics, now with arrows and dots.
- Enhancement: Linked settings (multisig, trick pins, backup password, hsm users and utxo cache) separation for new main secret.
- Rename
Unchained Capital
toUnchained
- Bugfix: Correct
scriptPubkey
parsing for segwit v1-v16 - Bugfix: Do not infer segwit just by availability of
PSBT_IN_WITNESS_UTXO
in PSBT. - Bugfix: Remove label from Bitcoin Core
importdescriptors
export as it is no longer supported with ranged descriptors in version24.1
of Core. - Bugfix: Empty number during BIP-39 passphrase entry could cause crash.
- Bugfix: Signing with BIP39 Passphrase showed master fingerprint as integer. Fixed to show hex.
- Bugfix: Fixed inability to generate paper wallet without secrets
- Bugfix: Activating trick pin duress wallet copied multisig settings from main wallet
- Bugfix: SD2FA setting is cleared when seed is wiped after failed login due to policy SD2FA enforce. Prevents infinite seed wipe loop when restoring backup after 2FA MicroSD lost or damaged. SD2FA is not backed up and also not restored from older backups. If SD2FA is set up, it will not survive restore of backup.
- Bugfix: Terms only presented if main PIN was not chosen already.
- Bugfix: Preserve defined order of Login Countdown settings list.
- Bugfix: Remove unsupported trick pin option
Look Blank
fromif wrong
(not supported by bootrom). - Bugfix: v5.1.3 release had padding issue which causes red light on install.
🧙 Edge Version 6.1.0X [development purposes]#
Find binary here and view release notes. Advanced features currently in Edge:
- Miniscript and MiniTapscript support (see
docs/miniscript.md
) - New Enhancement: Tapscript up to 8 leafs
- Taproot spending, signing, multisig.
- BIP-129 Bitcoin Secure Multisig Setup (BSMS)
This preview version of firmware has not yet been qualified and tested to the same standard as normal Coinkite products. It is recommended only for developers and early adopters and experimental use. DO NOT use for large Bitcoin amounts.
Mk4: Version 5.1.2 - Apr 7, 2023#
- Enhancement: Support all
SIGHASH
types (previously onlySIGHASH_ALL
was supported). This can enable specialized Bitcoin transactions involving multiple signers and even limited changes to the transaction after signing. To enable the most dangerous SIGHASH modes, you must changeAdvanced -> Danger Zone -> Sighash Checks
. Warnings are shown for all of the new SIGHASH modes regardless of this setting. - Enhancement: SeedXOR now supports 12 and 18 words mnemonics.
- Enhancement: Signing memory, speed optimizations.
- Enhancement: Docker repro build container improvements (non-privileged container)
- Bugfix: After extended private key and TAPSIGNER backup import into blank wallet, users needed to manually reboot Coldcard.
- Bugfix: Do not set SIGHASH type on foreign PSBT inputs
- Bugfix: "Validating..." screen would be shown twice in some cases. Improves signing performance.
Mk4: Version 5.1.1 - Feb 27, 2023#
- New Feature: "MicroSD card as Second Factor". Specially marked MicroSD card must be
already inserted when (true) PIN is entered, or else seed is wiped. Add, remove and check
cards in menu:
Settings -> Login Settings -> MicroSD 2FA
- New Feature: Import TAPSIGNER encrypted backup as main or ephemeral seed, for PSBT signing.
- New Feature: Detached Bitcoin signature files (most exports)
- Files exported are now signed with a detached signature. Look for a
.sig
file with the same name, and verify signature with your favourite Bitcoin tools. See "Signed Exports" indocs/msg-signing.md
fo more information. - Coldcard can now verify signed files:
- SD card and Virtual disk
Advanced/Tools -> File Management -> Verify Sig File
- NFC
Advanced/Tools -> NFC Tools -> Verify Sig File
- SD card and Virtual disk
- Files exported are now signed with a detached signature. Look for a
- Address Explorer:
- Enhancement: Application-specific derivation paths in
Address Explorer -> Applications
- Bugfix: Change value was ignored when generating addresses file
- Enhancement: Application-specific derivation paths in
- Import Enhancements:
- Add import multisig wallet via Virtual Disk
- Add import extended private key via Virtual Disk and via NFC
- Import seed in compact/truncated form (just 3-4 letters of each seed word)
- Import extended private key as ephemeral seed
- Export Enhancements:
- Samourai POST-MIX and PRE-MIX descriptor export options added
- Lily Wallet added
- Ability to export all supported wallets via NFC (instead of SD card only)
- Change electrum export file name from 'new-wallet.json' to 'new-electrum.json'
- Allow export of Wasabi skeleton for Bitcoin Regtest.
- Backup Enhancement:
- Option to save the backup file's encryption password for next backup. Then next backup is quick and simple: no need to record yet another 12 words.
- Enhancement: During seed generation from dice rolls, enforce at least 50 rolls for 12 word seeds, and 99 rolls for 24 word seeds. Statistical distribution check
- Enhancement: Single signature wallet generic descriptor export
Advanced -> Export Wallet -> Descriptor
. Both new format with internal/external in one descriptor<0;1>
and standard with two descriptors are supported. added to prevent users from generating low-entropy seeds by rolling same value repeatedly. - Bugfix: Offer import/export from/to Virtual Disk in UI even if SD Card is inserted.
- Bugfix: Recalculate extended key saved in settings upon chain change (BTC, XTN, XRT).
- Bugfix: Provide correct derivation path (m/84'/1'/0') for testnet Wasabi export.
- Bugfix: Properly display UX checkmark only if testnet (XTN, XRT) is enabled
in
Settings- > Danger Zone -> Testnet Mode
. - Docs: Add
docs/rolls12.py
script for verifying dice rolls math for 12 word seeds. - Bugfix: v5.1.0 would not install over MicroSD; 5.1.1 was made to replace it.
Mk4: Version 5.0.7 - Oct 5, 2022#
- NFC Enhancements:
- In older versions, multisig NFC import not offered if a MicroSD card was inserted, now this option provided Settings > Multisig Wallets > Import via NFC. NFC has to be enabled for this option to be visible in the menu.
- NFC message signing (Advanced/Tools > NFC Tools > Sign Message). Send message in same format as Sign Text File over NFC, approve signing on Coldcard and send signed ASCII-armored message back over NFC.
- Show address over NFC (Advanced/Tools > NFC Tools > Show Address).
- Bugfix: Improved NFC commands exception handling
- Bugfix: Share single address over NFC from address explorer menu.
- HSM Enhancements:
- Dynamic HSM Whitelisting. Foreign outputs can be attested-to by signing them with private key corresponding to the address specified in HSM policy. Attestation signature MUST be provided in PSBT in a new proprietary field.
- HSM policy hash is now displayed during first activation and in the HSM status response. This enables fast comparison against known policy hashes.
- Thanks to @straylight-orbit for above items!
- Now ignores HSM commands over USB, by default. To enable and use HSM features, go to Advanced/Tools > Enable HSM > Enable
- New Feature: Ephemeral Seeds: Advanced/Tools > Ephemeral Seed (more info in
docs/ephemeral.md
) - Enhancement: New menu wraparound settings which allow you to scroll past top and bottom of any menu (Settings > Menu Wrapping).
- Enhancement: Allow import of new descriptor type which specify both internal/external
in single string (ie.
../<0;1>/..
). We still export in older format. - Enhancement: add ability to specify address format in text file to be signed (3rd line of file)
- Bugfix: Correct parsing of unknown fields in PSBT: they are now passed through.
- Bugfix: Using lots of trick pins (7+), could lead to a case where the Coldcard would not accept the main pin, but trick pins continued to work. This release adds a workaround to avoid getting into that situation, and new units from the factory will ship with an updated bootrom (version 3.1.5).
Mk3: Version 4.1.9 - Jun 26, 2023#
- Bugfix: QR codes could not be rendered in 4.1.8 release due to a regression.
Mk3: Version 4.1.8 - Jun 19, 2023#
- Please use 4.1.9 instead of this release, see above.
- Bugfix: "Validating..." screen would be shown twice in some cases. Improves signing performance.
- Bugfix: Reproducible builds corrected.
Mk3: Version 4.1.7 - Nov 14, 2022#
- Upgrade Bugfix: Upgrades to 4.1.6 version using SD Card did not work due to an obscure alignment bug. USB upgrade did work. A workaround has been added for this release. No other changes.
Mk3: Version 4.1.6 - Oct 5, 2022#
- Bugfix: order of multisig wallet registration does NOT matter in PSBT signing
- Bugfix: allow unknown scripts in HSM mode
- Enhancement:
OP_RETURN
is now a known script and is displayed in ascii if possible
Mk3: Version 4.1.5 - May 4, 2022#
- Enhancement: Support P2TR outputs (pay to Taproot) in PSBT files. Allows
on-screen verification of P2TR destination addresses (
bc1p..
) so you can send your BTC to them. Does not support signing, so you cannot operate a Taproot wallet with Mk3 COLDCARD as the signing device. - Bugfix: Yikes error shown during BIP-85 menu operation.
- Enhancement: Rename "Derive Entropy" to "Derive Seed B85" to match Mk4 menus
Mk3: Version 4.1.4 - Apr 26, 2022#
- Enhancement: if an XFP of zero is seen in a PSBT file, assume that should be replaced by our current XFP value and try to sign the input (same for change outputs and change-fraud checks). This makes building a workable PSBT file easier and could be used to preserve privacy of XFP value itself. A warning is shown when this happens.
- Enhancement: "Advanced > Export XPUB" provides direct way to show XPUB (or ZPUB/YPUB) for BIP-84 / BIP-44 / BIP-49 standard derivations, as a QR. Also can show XFP and master XPUB.
- Bugfix: Updated domain name from
coldcardwallet.com
tocoldcard.com
in docs and few on-screen messages. - Bugfix: allow sending to scripts that we cannot parse, with a warning, to support
OP_RETURN
and other outputs we don't understand well (yet).
Older releases and their changes are listed here, the full source code, hardware details, and much more can be found in our repository on github. Other downloads are listed here.
Upgrading Your COLDCARD's Firmware#
Mark 1 Firmware Limit
Do not attempt to upgrade a Mark 1 COLDCARD beyond firmware version 3.0.6 (2019-12-19T1623-v3.0.6)!
Mark 1 hardware is no longer supported. Newer firmware versions will completely brick a Mark 1 COLDCARD. Look for the revision (Mark 1, Mark 2, Mark 3) on the back of your COLDCARD before you begin upgrading.
Introduction#
About Upgrades#
Stay up to date on firmware releases - follow our Twitter account @COLDCARDwallet, or bookmark the Coinkite Blog.
Firmware upgrades provide new features, enhancements, bugfixes, and the latest security updates to your COLDCARD.
Firmware upgrade files have a .dfu
file extension and should be approximately 690 KB in size. We use the abbreviation 20...-coldcard.dfu
to represent the full firmware file name. Make sure to use the full file name in your commands.
COLDCARDs only load and run files signed by a Coinkite Inc. approved key.
Upgrade Menu#
The Upgrade
menu allows you to load an upgrade .dfu
file from a microSD card.
Upgrade Menu Options#
Show Version
displays the version numbers of the firmware currently loaded on your COLDCARD.
From MicroSD
lets you start the firmware upgrade process.
Bless Firmware
marks the firmware upgrade as approved by the main PIN holder. This step is necessary if your COLDCARD loses power before the upgrade is confirmed.
Alternate Upgrade Methods#
These instructions use a microSD card to upgrade the firmware. You
can also upgrade by using the command-line tool or the
Electrum plugin. On the Mk4,
if USB drive emulation is enabled, you can simply copy the dfu
file
onto the COLDCARD.
Downgrading Firmware and Older Versions#
Downgrading to an older firmware version is discouraged and may be blocked depending on your current firmware. Some firmware releases will prevent the bootloader from accepting older versions due to bugs or security issues found in older firmware. A limited selection of previously released firmware is available here.
Upgrade Procedure Using MicroSD#
What You'll Need#
- One COLDCARD
- microSD card (up to 32 GB capacity, FAT32 or FAT12 format)
- Micro USB cable, power-only preferred
- Power source for Micro USB cable, COLDPOWER or AC to USB adapter preferred
- Internet-capable device for downloading and saving files
What You'll Do#
Check Your Current COLDCARD Firmware Version#
- Connect the COLDCARD to a power source with the Micro USB cable to turn it on.
- Enter your PIN to unlock the COLDCARD.
- Select
Advanced > Upgrade > Show Version
. - Compare the version shown on the screen with the latest version shown on coldcard.com/docs/upgrade. If your COLDCARD doesn't have the latest firmware version, it's time to upgrade.
Get the Latest Firmware#
- Go to coldcard.com/docs/upgrade if you're not already here. The latest firmware release will be at the top of the page.
- Save the
20...-coldcard.dfu
file to your microSD card or a folder on your computer. - Decide whether you will verify the firmware's hash and signature (strongly recommended) or load the firmware on your COLDCARD without verification.
- Verifying? Go to the verification instructions.
Load the Latest Firmware on your COLDCARD#
- Save the
20...-coldcard.dfu
file to your microSD card if you haven't done so already and eject the card once the file is saved. - Make sure your COLDCARD is turned on and unlocked.
- Select
Advanced > Upgrade > From MicroSD
. - Press OK (✔) on your COLDCARD when you are prompted to pick the firmware image.
- Select the firmware file.
- The screen will say
"Loading. . ."
. Be patient, this process takes time.
Note: When the screen changes to Verifying
, the red LED will
light up and stay lit until the firmware upgrade is complete. The
red CAUTION LED lets you know changes are being made or have
been made to your COLDCARD. If the COLDCARD is turned off after
the new firmware is installed but before the first successful
login, you will need to
bless the firmware
to turn the red LED off.
Do not turn off power to the Mk4 during it's 15-second upgrade process. Doing so will put it into a special recovery mode which requires a specially-prepared MicroSD card to be used.
Confirm and Finish Upgrade#
- Enter your PIN prefix when prompted after the COLDCARD reboots.
- Verify whether or not you recognize the two words displayed on the screen. These words are hardware-specific to ensure you have the correct device. A different COLDCARD will display different words.
- Enter the rest of your PIN when prompted.
- The COLDCARD will perform another verification and the green GENUINE LED will light up.
- Inspect your upgrade by selecting
Advanced > Upgrade > Show Version
. The firmware version you loaded will be displayed. You have successfully upgraded your COLDCARD's firmware!
Video Tutorial#
Watch Max Hillebrand perform the firmware upgrade and verification process using Debian and a Mark 2 COLDCARD.
Optional Steps#
Red LED Lit After Restart? Bless the Firmware#
The red CAUTION LED is a safety feature warning you of unconfirmed changes to your COLDCARD. Only the main PIN holder can confirm changes. If you load new firmware and turn off the device before confirming the upgrade, the CAUTION LED will be lit the next time you turn on your COLDCARD. Blessing the firmware tells the COLDCARD that you are aware of and approve of the firmware upgrade.
- Follow the prompts on the screen to log in to your COLDCARD.
- Select
Advanced > Upgrade > Bless Firmware
. - The screen will say
Verifying
the green GENUINE LED will light up confirming your approval of the new firmware.
Once the firmware is blessed, your COLDCARD will light up the green LED on future startups.
Don't Trust. Verify the Firmware#
Verifying the firmware's hash and signature requires intermediate to advanced computer skills. It uses extra tools and adds steps, but if you use a COLDCARD, you're probably security-conscious. In that case, you may find the extra effort to be worth the peace of mind you'll get from knowing your firmware is safe and correct.
Note: PGP signature verification requires GPG. Debian and other Linux distributions include GPG. Mac and Windows users who have not already installed GPG will need to do so. Operating system-specific instructions contain links to tool downloads.
Verifying on Mac#
These instructions use GPG Keychain, a component of the GPG Suite from GPGTools.
You can also follow along with our video tutorial, How to Verify COLDCARD's Firmware.
Confirm the Hash
- Open signatures.txt so you can view its contents.
- Open Terminal, navigate to the directory where you saved the firmware and use the command
shasum -a256 20...-coldcard.dfu
. - Resize or reposition the windows so you can see both the Terminal and
signatures.txt
file at the same time. - Compare the output values in Terminal with the line of text in the
signatures.txt
file next to the firmware version you saved. The hash is confirmed if the values are the same.
Verify the PGP Signature
- Save the signatures.txt file in the same location as the new firmware file.
- Save the public key
4589779ADFC14F3327534EA8A3A31BAD5A2A5B10
as anew-pubkey.txt
file in the same location as the firmware andsignatures.txt
files. - Open GPG Keychain.
- Click the Import button and navigate to
new-pubkey.txt
. Select the file and click Open. A pop-up message should appear saying "Import successful". - Open Terminal and enter
gpg --verify signatures.txt
. - The output in Terminal should include
Good signature from...
. It is normal to seeWARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner.
You may ignore the warning, the signature is verified.
Once the hash and signature are verified, load the latest firmware on your COLDCARD.
Verifying on Linux#
Confirm the Hash
- Open signatures.txt so you can view its contents.
- Use the command line to navigate to the directory where you saved the firmware and enter the command
sha256sum 20...-coldcard.dfu
. - Resize or reposition the windows so you can see both the command output and
signatures.txt
file at the same time. - Compare the output value from the command with the line of text in the
signatures.txt
file next to the firmware version you saved. The hash is confirmed if the values are the same.
Verify the PGP Signature
- Save the signatures.txt file in the same location as the new firmware file.
- On the command line, enter
curl "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xA3A31BAD5A2A5B10" | gpg --import
to import the public key. - Next, enter
gpg --verify signatures.txt
to verify the file's signature versus its content. - The command output should include
Good signature from...
. It is normal to seeWARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner.
You may ignore the warning, the signature is verified.
Once the hash and signature are verified, load the latest firmware on your COLDCARD.
Verifying on Windows#
These instructions use Kleopatra, which is a part of Gpg4win (GNU Privacy Guard for Windows). You only need the GnuPG Privacy Guard and Kleopatra components to verify the PGP signature.
Kleopatra requires you to have an OpenPGP signature to complete verification. If you don't have a signature to import, you can make one in Kleopatra.
Confirm the Hash
- Open signatures.txt so you can view its contents.
- Open Command Prompt and enter
certutil -hashfile C:\..\20...-coldcard.dfu SHA256
, whereC:\..\20...-coldcard.dfu
is the full path to the saved firmware file. - Resize or reposition the windows so you can see both the Command Prompt output and
signatures.txt
file at the same time. - Compare the output values in Command Prompt with the line of text in the
signatures.txt
file next to the firmware version you saved. The hash is confirmed if the values are the same.
Verify the PGP Signature
- Save the text from signatures.txt with an
.asc
file extension in the same location as the saved firmware file. Do not save the file as.txt
, Kleopatra will not recognize it. - Save the public key
4589779ADFC14F3327534EA8A3A31BAD5A2A5B10
as an.asc
file in the same location as the firmware andsignatures.asc
files. - Open a browser and go to keybase.io/DocHex. Click on the text next to the key icon to open the public key window. You will need this window for a later step.
- Open Kleopatra and click
Import...
. - Navigate to the public key
.asc
file and open it. - You will be asked to check the fingerprint of the file and given suggested options. The Keybase public key window is the trusted website. Click
Yes
. - A Certify Certificate window will show the file's fingerprint, your certification, and the fingerprint's owner - in this case, Peter D. Gray. Resize or reposition the Certify Certificate window and the browser window opened in step 3 so you can see them both at the same time.
- Make sure the fingerprints in each window match and click
Certify
. If you have a passphrase on your certificate, you'll be asked to enter it. A pop-up box should appear saying, "Certification successful." ClickOk
. - Click
Decrypt/Verify...
and opensignatures.asc
. - Kleopatra will verify the signature. You may save or discard the file Kleopatra generates, it is not needed. The signature is verified.
Once the hash and signature are verified, load the latest firmware on your COLDCARD.