Skip to content

BIP-39 Passphrase

main-menu

Introduction#

About BIP-39#

Selecting New Wallet when setting up a COLDCARD® generates 24 seed words for you to record. Those words allow you to recover your Bitcoin funds if your wallet is lost, stolen, or destroyed. Your seed words come from a list of 2048 words specified by a standard known as BIP-39. BIP-39 defines how seed words are generated and converted into your wallet's seed. BIP-39 also gives you the option to apply a passphrase to your seed words. Applying a passphrase to your seed words creates a new, unique wallet separate from the one made during setup.

Because adding a passphrase to your seed words creates a new wallet, any other passphrase you enter (including a passphrase entered incorrectly) will create yet another new wallet based on your seed words. Each new wallet has its own master private key and will be empty until or unless it gets used. Using passphrases makes it possible to generate approximately 5.9 × 10197 different wallets based on your original seed words.

BIP-39 adds to an earlier Bitcoin Improvement Proposal, BIP-32, which establishes how to create a tree of public and private keys and build a hierarchical deterministic wallet (HD wallet) structure to use those keys. Applying a passphrase to your seed words generates a master BIP-32 wallet key and provides the extended fingerprint (XFP) as an identifier.

The XFP is a hash of the BIP-32 wallet created by combining your BIP-39 seed words and unique passphrase. The only way to verify your passphrase is correct is to compare the XFP displayed when you made the wallet to the XFP of the wallet you are accessing. The XFP of each individual wallet should be documented for future reference.

Video: Tutorial: Applying a Passphrase

Passphrases and Your COLDCARD#

Passphrases do not change how your COLDCARD works. Options and functions are the same with or without a passphrase.

The first wallet you make on your COLDCARD uses an empty string for a passphrase. You can use the same COLDCARD to create and access multiple wallets by making up new passphrases and applying them to your original seed words. Your first wallet will not be affected; any funds linked to it will be safe.

Your COLDCARD doesn't store passphrases, therefore backup files don't contain passphrases. Backups capture the original seed, not the extended private key created by the passphrase. Passphrases can be stored on a microSD card whenever they are applied.

You must enter the passphrase each time you want to use the wallet associated with it. Entering the passphrase can be done using the keypad, the command-line tool, or a microSD card.

Using passphrases improves security and flexibility. Passphrases are a powerful alternative to the duress PIN due to the nearly unlimited number of possible wallets.

There is no validation performed on your passphrase. Entering an incorrect passphrase will open a different wallet and you will not find your Bitcoin. However, you can — and should — perform your own validation when using a passphrase. Your COLDCARD will show you an 8-digit hexadecimal number when you apply a passphrase. This 8-digit number is the new wallet's extended fingerprint (XFP). Write this number down so you can check the XFP each time you access the wallet.

Passphrase Security#

Thanks to the cryptographic design of BIP-39, a weak passphrase does not lessen the safety of the other wallets or help reveal the seed words. However, if an attacker had your seed words, they could exhaustively search for other wallets. The usual warnings about using longer, more complex passphrases apply.

Passphrase Menu#

passphrase menu

Passphrase Menu Options#

Restore Saved Only appears when a microSD card is in the COLDCARD. Saved passphrases can be selected and applied from a microSD card.

Edit Phrase Enter characters. Once selected, use keys 1 through 4 to switch between letters, numbers, symbols, and upper or lower case. Also displays the passphrase for verification or editing.

Add Word Lets you choose a word from the BIP-39 word list (2048 choices with 6 variations each). You can select a word and then edit it with Edit Phrase.

Add Numbers Enter up to 32 numeric digits using the keypad. This is faster than using Edit Phrase for long numbers.

Clear All Clears what you have entered to start over.

APPLY Applies the passphrase to your seed words and gives you the option to save the passphrase to a microSD card.

CANCEL Cancels the process.

Passphrase Procedure#

What You'll Need#

  • COLDCARD with firmware 2.0.0 or later
  • Micro USB cable, power-only preferred
  • Power source for Micro USB cable, COLDPOWER or AC to USB adapter preferred
  • Optional: microSD card (up to 32 GB capacity, FAT32 or FAT12 format) for saving the passphrase

What You'll Do#

Create a Passphrase#

Passphrases must be: - No longer than 100 characters. - ASCII characters only (no accented letters): - Upper case letters - Lower case letters - Numbers - Symbols

You can use any combination of letters, numbers, and symbols. Keep in mind, the Add Word menu gives you the option to select a word from the BIP-39 word list which includes 6 different variations for each of the 2048 words. This makes using words, or parts of them, much easier.

Enter the Passphrase#

Alternate Entry Method - Command-Line Tool#

The passphrase can be sent to the COLDCARD over our encrypted USB protocol, using our command-line tool: ckcc. Passphrase confirmation happens on the COLDCARD. Using ckcc is a convenient way to enter complex passphrases, assuming you trust the desktop computer and any keyloggers that might be present.

Standard Entry Method - COLDCARD Only#
  1. Connect the COLDCARD to a power source with the Micro USB cable to turn it on.
  2. Enter your PIN to unlock the COLDCARD.
  3. Select Passphrase.

The screen will display information and instructions:

You may add a passphrase to your BIP-39 seed words.  This creates
an entirely new wallet, for every possible passphrase.

By default, the Coldcard uses an empty string as the passphrase.

On the next menu, you can enter a passphrase by selecting individual
letters, choosing from the word list (recommended), or by typing
numbers.

Please write down the fingerprint of all your wallets, so you can
confirm when you've got the right passphrase. (If you are writing
down the passphrase as well, it's okay to put them together.) There
is no way for the Coldcard to know if your password is correct, and
if you have it wrong, you will be looking at an empty wallet.
  1. Press OK (✔) to continue.
  2. Enter your passphrase. You can use any combination of the three entry options, Edit Phrase, Add Word, and Add Numbers. Use the X key to delete unwanted characters. If you need to start over, select Clear All.

Example: If your passphrase was Baby12345678!!!, you could choose the word "Baby" from the Add Word menu, add the numbers with Add Numbers and then go back to Edit Phrase to complete it with !!!.

  1. Use Edit Phrase to display your passphrase, check it for accuracy, and edit if necessary.
  2. Press OK (✔) when you have the correct phrase shown on the screen.

Apply the Passphrase#

  1. Select APPLY. The screen will show the 8-digit hexadecimal extended fingerprint (XFP) and the message Above is the master key fingerprint of the new wallet. The passphrase for this XFP is not in effect yet.

after apply

Write Down Your Wallet's Extended Fingerprint (XFP)

We recommend writing the XFP on paper for later reference. It's safe to store the XFP with your passphrase if you write both of them down.

  1. You have three options:
    • Press X to abort passphrase application and keep editing the passphrase. Selecting CANCEL after an abort will stop the process.
    • Press OK (✔) to use the new wallet created by the passphrase.
    • Press 1 to save the passphrase to a microSD card. Make sure the microSD card is already in the COLDCARD. Your passphrase value will be encrypted and saved on the card for future use. If you don't have a microSD card available now, you can save your passphrase to one when you enter it later.

If you select OK (✔) or 1, the COLDCARD will return to the main menu and the passphrase will be in effect until you use Secure Logout or turn off the COLDCARD.

Saved Passphrases#

Passphrase values are stored in the /.tmp.tmp file on the microSD card. The values are encrypted with AES-256 (CTR mode) using a key derived from the seed words and a hash of the microSD card's unique serial number, restricting the file to the specific card. You cannot copy the encrypted file to another card.

Video Tutorial#

Watch our passphrase video tutorial: COLDCARD Passphrase (BIP39) features. Using it, Locking it down, and encrypted MicroSD.

Using Your COLDCARD with a Passphrase#

Since your COLDCARD does not store passphrases, entering an existing passphrase is the same process as applying a new one. The same options are available every time.

Using a Saved Passphrase#

example restore

  1. Insert the microSD card containing the passphrase into the COLDCARD's microSD slot.
  2. Enter your PIN to log in and select Passphrase > Restore Saved.
  3. If you have multiple passphrases stored on your microSD card, you will see a list of passphrases showing one or more characters with the rest replaced by asterisks (*). The COLDCARD will show just enough to allow you to determine which passphrase to select.
  4. Select the passphrase you want and press OK (✔). The wallet's extended fingerprint (XFP) will be shown with the message "Passphrase restored." Make sure this is the XFP you expect.

The selected passphrase is in effect until you use Secure Logout or turn off the COLDCARD.

Extended Fingerprint (XFP) Tips#

  • Verify the XFP of your current wallet by selecting Advanced > View Identity. The Master Key Fingerprint displayed is the wallet's XFP.

  • Press X to go back and adjust your passphrase if the XFP displayed is not what you expected.

  • Partially Signed Bitcoin Transaction (PSBT) files reference the wallet XFP value. If you try to sign a PSBT using the wrong passphrase, you will get an error message that includes the correct XFP.

Using a Passphrase with Electrum#

Enter your passphrase before starting Electrum or opening your desktop wallet file. Starting Electrum or opening your desktop wallet file before entering your passphrase will cause them to access your default wallet (empty passphrase) and produce errors. If you create a skeleton Electrum wallet, do so after entering the passphrase of the new wallet.

Optional Feature#

Lock Down Seed#

What Locking Down the Seed Does#

Your 24 seed words combined with a passphrase create a master BIP-32 key representing a full BIP-32 hierarchical deterministic wallet. BIP-39 lets you add more passphrases to your seed words to generate more of these wallets. You unlock the seed words with your PIN and enter the passphrase to get to the intended wallet.

Your COLDCARD calculates the extended private master key (XPRV) value for your seed words and passphrase when you choose to lock down the seed. This value replaces the seed words and passphrase with the value as the wallet secret inside the secure element.

The wallet's characteristics are the same as before locking down the seed. Your COLDCARD will no longer offer the Passphrase menu option but is otherwise unchanged. Entering your PIN will get you to your wallet, no passphrase needed.

Locking down the seed creates a BIP-32 wallet by removing BIP-39 traits (seed words and passphrase), leaving BIP-32 hierarchical features and the rest of your COLDCARD's functions intact.

Lock Down Seed Procedure#

Seed Words Are Destroyed

This command replaces the seed words inside the secure element. There is no way to recover the original seed words or passphrase.

lock down menu

  1. With your COLDCARD turned on and unlocked, select Advanced > Danger Zone > Lock Down Seed.
  2. Read the confirmation message on your screen.
This operation computes the extended master private key using your
BIP-39 seed words and passphrase, and then saves the resulting value
(xprv) as the wallet secret.

The seed words themselves are erased forever, but effectively there
is no other change. If a BIP-39 passphrase is currently in effect,
its value is captured during this process and will be 'in effect'
going forward, but the passphrase itself is erased and unrecoverable.
The resulting wallet cannot be used with any other passphrase.

A reboot is part of this process. PIN code, and funds are not affected.
  1. Press OK (✔) to confirm. Your COLDCARD will restart to lock down the seed.
  2. Enter your PIN. The Passphrase option will not appear in the menu.
  3. Make sure to check the Master Key Fingerprint as this is your wallet's XFP. Select Advanced > View Identity to verify it is correct.
XPRVs and Backup Files#
  • New backup files will show the XPRV (extended private key) as the wallet secret. The seed words are no longer known to the COLDCARD, so they do not appear in the backup file.

  • It is possible to operate a COLDCARD by importing an XPRV or master secret (bytes) and not use any seed words. The Passphrase menu will not be available as it cannot be used.

Why Lock Down the Seed?#

You may need to create multiple wallets based on the same seed words for delegation to other people. Save a backup file from the default wallet created by your set of seed words. Get the required number of COLDCARDs, choose Import Existing during setup and load the same backup file onto each of them. Give each COLDCARD its own passphrase and then lock down the seed. Your seed words will not be known to any of the devices and remain secure.