Overview

What's BitKey?

BitKey is a bootable system image based on Debian containing everything you need to perform highly secure air-gapped Bitcoin transactions. You don't need to install it to a hard drive because it runs live from RAM. You just write the ISO image to a USB drive or burn it to CDROM.

Under the hood it contains a swiss army knife of handy Bitcoin tools that support a wide range of usage models, including a few very secure ones which would otherwise be difficult to perform. We created BitKey because we wanted something like it for our own use.

We're avid Bitcoin fans but after going to our first local Bitcoin meetup we discovered the elephant in the room was that there was no easy way to perform cold storage Bitcoin transactions where the wallet lives on an air-gapped system physically disconnected from the Internet.

The idea was to see if we could use the TurnKey GNU/Linux build system to create a self-contained read-only CD/USB stick with everything you need to perform Bitcoin transactions with as much security as you wanted - including highly secure air-gapped Bitcoin transactions.

How do I use BitKey?

We've documented several common use cases right on this website's usage section. Click on the various boot modes for instructions.

How secure are air-gapped systems?

It depends! Air-gapped systems raise the bar because they are physically prevented from communicating with the Internet. That prevents an attacker that doesn't have physical access from actively attacking the computer and/or remote controlling it.

But like all other security measures air-gaps are no silver bullet, especially when you don't trust the system behind the air-gap. There are many ways an evil air-gapped system can betray its user, including creating bad transactions and smuggling out secret keys via covert channel (e.g., USB keys, high frequency sound, covert activation of Bluetooth/wifi chipset, etc.)

Do I have to use BitKey on a separate air-gapped computer?

Not if you don't want to, or if you just don't need the extra security. BitKey also works online in two modes: cold-online and hot-online. See the usage section for details.

How much security does BitKey provide?

It depends! At one extreme, using BitKey in just the right way is currently the closest you can get to perfectly secure Bitcoin transactions (without doing them in your head).

Even when you use BitKey in the most insecure mode possible (e.g., hot-online) it still provides better security than 99% of Bitcoin users are getting from their web wallets and Bitcoin phone apps.

If the theft of hundreds of millions of dollars worth of Bitcoin from the Bitcoin exchanges has left you, like us, with a healthy sense of paranoia, then you'll want to use BitKey in the most secure way possible in which case nobody in the world is getting better security for their Bitcoin transactions. Nobody.

How does BitKey compare with a hardware wallet like Trezor?

In terms of pricing and availability, BitKey is free and runs on ubiquitous general purpose computers.

In terms of security, it can provide equivalent or better security than a hardware wallet, depending on how you use it.

In terms of convenience it's hard to beat a hardware wallet. Using BitKey to implement the most paranoid, trust-minimized workflows provides superior security at the price of not being as easy to use.

For an in-depth analysis, read the discussion with Trezor developer Tomas Dzetkulic (better security than Trezor?) and judge the pros and cons for yourself.

Do I need to trust BitKey not to steal my Bitcoin?

Not if you're careful. In fact, if you have reason to worry we encourage you not to trust BitKey. In the words of our dear leader: trusted third parties are a security hole.

As a Bitcoin swiss army knife BitKey supports many usage models. What's interesting is that this includes at least one use case which doesn't require you to trust BitKey at all. We call it the If I tell you I'll have to kill you usage model. It provides almost perfect security even if BitKey itself is rotten to the core.

Also, if you don't trust the binary version, you can always build BitKey from source.

Do I have to be ultra paranoid to use BitKey?

No. We understand that people routinely trade off security for convenience, otherwise they wouldn't get anything done.

We recognize that there is an inescapable trade off between convenience and security and that risk is proportional to the value of your wallet. So it doesn't make sense to enforce any specific trade off. We want BitKey to help make the most paranoid usage model practical for day to day use but at the same time, we want to let the user decide how high (or low) to raise the bar. It should be your choice.

Is BitKey perfect?

No. There's room for improvement. Mostly in terms of improving the usability and reducing the potential for human error. Also, adding support for locally attached printers so you can print paper wallets. Stuff like that.

But for a solution to be useful it doesn't need to be perfect, just better than the alternatives for some use cases.

Unfortunately, the problem is many people currently using Bitcoin don't understand the risks they are taking and place too much trust on incredibly insecure solutions such as web based Bitcoin wallets, accessed from a general purpose PC that is installed, configured and used by a person who is not and will never be a security expert. That might be OK for very low value wallets that you wouldn't mind losing but beyond that it is very foolish.

Installing BitKey

BitKey on CDROM: use your favorite program to burn the ISO to CDROM. Nothing special. CDROMs are naturally read-only and tamper resistant.

BitKey on USB: If you don't burn BitKey to a CDROM, writing BitKey to a USB stick with a hardware read-write toggle (e.g., Kanguru FlashBlu) is the next best thing.

On USB sticks without write protection, you can remove the BitKey USB after booting as an additional security measure. BitKey loads into RAM so after booting you no longer need the USB.

1. Insert USB stick and detect the device path:

           $ dmesg|grep Attached | tail --lines=1
           [583494.891574] sd 19:0:0:0: [sdf] Attached SCSI removable disk
           

2. Write ISO to USB:

           $ sudo dd if=path/to/bitkey.iso of=/dev/sdf
           $ lsblk | grep sdf
           sdf                                8:80   1   7.4G  1 disk
           └─sdf1                             8:81   1   444M  1 part
           

Data storage flash drive

By default, BitKey stores your wallet encrypted on a USB flash drive AKA USB stick.

It expects your flash drive to be vfat formatted. This is the standard format for store bought drives. If this isn't the case, BitKey may have trouble detecting your drive. In that case you can reformat the drive from Windows, or on Linux / BitKey using the following steps:

1. Insert data storage flash drive and detect the device path:

       $ dmesg|grep Attached | tail --lines=1
       [583494.891574] sd 19:0:0:0: [sda] Attached SCSI removable disk
       

2. Reformat the drive:

       $ sudo mkfs.vfat /dev/sda1
       mkfs.fat 3.0.27 (2014-11-12)
       

Usage

Demo

Boot modes

BitKey Live CD/USB supports three modes of operation selected from a boot time menu.

Mode	Wallet	Transactions	Security	Background	Convenience
cold-offline (?)	create	sign	high	green for safe	less
cold-online (?)	watch	prepare	high	blue for info	less
hot-online (?)	create & watch	prepare & sign	medium	red for danger	more

High security - Cold storage boot modes

Two cold storage modes:

1. cold-offline: create wallet, sign transactions. In this mode, the desktop background is green (mnemonic for cool and safe)

2. cold-online: watch wallet, prepare transactions. In this mode, the desktop background is blue (mnemonic for cool and informative)

If the instructions are carefully followed, cold storage modes creates an airgap which ensures that your wallet's private keys are never loaded into RAM on a computer connected to the Internet.

Medium security - Hot-online boot mode

In this mode the desktop background is red (mnemonic for hot and dangerous)

Allows you to create & watch wallet, prepare & sign transactions.

In hot online mode, the private keys are known to a computer connected to the Internet. This is the most convenient mode because you only need one computer. After booting BitKey resides in RAM and saves nothing to your hard drive.

The flip side is smaller security margins:

• You need to trust that your copy of BitKey hasn't been tampered with and that the original signed BitKey image hasn't been compromised.

• If you use a network enabled app (e.g., Chromium) and an attacker exploits a zero-day vulnerability to gain access to your online system, say goodbye to those Bitcoins!

Low security - Hot storage on your PC/phone

In this mode you don't use BitKey or any hardware wallet type device. Your wallet's private keys are stored on your phone or PC and known to an Internet enabled device that is vulnerable (or will be sometime in the future) to the efforts of thieves who would like nothing more than to steal your Bitcoin.

You rely on the magical power of wishful thinking. You're not important enough to get hacked and any opportunistic malware infection you do get is not going to include any Bitcoin stealing functionailty. Right? Right! Good luck!

Paranoid brainwallet support

Hardest to use but leaves no trace of wallet keys in any storage medium. Minimizes trust in BitKey. Your wallet keys are only stored in your head.

This workflow is inspired by how Jason Bourne stores his Bitcoin.

Generating wallet

1. Boot BitKey in cold-offline mode, remove BitKey USB
2. Use Warpwallet to create a secure brainwallet
3. Save public Bitcoin address (e.g., scan qrcode)
4. To ensure private keys do not survive in RAM, turn off computer running BitKey and disconnect power source for 15 minutes.

After generating wallet, you can send Bitcoin to this address.

Warpwallet Public Service Announcement

Do not use Warpwallet without a salt

Unfortunately, Warpwallet makes it foolishly easy to skip the part where you input your e-mail as salt. Providing a salt mixes it in with the passphrase you provide. Non-experts may not realize how important this is. Without the salt, attackers can attempt to crack all Warpwallets simultaneously. With a salt, they have to divide their cracking power amongst a list of suspected e-mails. Cracking a million salted Warpwallets is a million times harder than cracking a million unsalted Warpwallets.

Using a salt gets you much more security risk free. There are no privacy implications and your e-mail is never exposed anywhere. In fact, you can use any e-mail you want, as long as you're sure you won't forget it.

Creating a secure passphrase and remembering it is hard

1. Humans are poor sources of randomness and much more predictable using statistical models than they think. Technology is ever moving forward and cracking techniques always get better, never worse. You may not be familiar with the state of the art, so be extra careful.

   The ideal passphrase is 6 to 8 truly random diceware words. If you're going to try and come up with a random passphrase yourself, be paranoid. They really are out to get you. At least use zxcvbn to measure passphrase strength. It's not perfect, but it should give you a clue. You'll want at least 65 bits of entropy for a salted warpwallet, especially if you are going to be storing funds long-term.

   DO NOT USE KNOWN PHRASES, QUOTES OR SENTENCES FROM A BOOK.

2. More wallets are lost to routine forgetfulness than sophisticated theft. If you're not continually accessing your Warpwallet there is a very high likelyhood you will eventually forget your passphrase after a few months or a few years. You only need to forget a single character for your wallet to be lost forever. This risk needs to be balanced with the risks of making a paper backup.

   Consider making a paper backup of your passphrase and destroying it only when you are absolutely sure you will not forget it, then use spaced reptition learning to ensure it stays in memory until you want to access the funds.

Thanks to Ryan Castellucci for inspiring this section.

Generating unsigned transaction step

This step is easiest to do from an Electrum watch-wallet on a PC, but you can also do it from BitKey:

1. Boot BitKey in cold-online mode, remove BitKey USB

2. Restore watch-only wallet and run Electrum, from command line:

           $ electrum restore $PUBLIC_ADDRESS
           $ electrum
           

3. Insert USB stick for storing unsigned transaction
4. Fill in recipient under Send tab and "Save" unsigned transaction to USB at /media/usb/

5. Shutdown/Reboot BitKey

Signing transaction step

1. Boot BitKey in cold-offline mode, remove BitKey USB

2. Insert USB stick where you stored unsigned transaction. Copy to RAM and remove from disk:

           $ cp /media/usb/unsigned.txt ~/     #  uses RAM for storage
           $ srm /media/usb/unsigned.txt       # secure delete unsigned transaction
           

3. Unplug USB stick

4. Use Warpwallet to restore brainwallet private key

5. Launch Electrum from command line so that it stores wallet in RAM:

           $ electrum -w /tmp/brainwallet
           

6. Import private key and sign transaction

   • In the Electrum Install Wizard, select 'Restore a wallet or import keys'
   • Cut and paste the private key, click Next
   • Click Next again (you don't need encryption for a wallet in RAM)
   • Tools > Load transaction > From file
   • Verify Outputs, Sign & Save signed transaction

7. Create a QRCode for the signed transaction:

   • Open Signed transaction in text editor
   • Open qrcode app: cut and paste hex of signed transaction

8. Scan qrcode of signed transaction with phone and broadcast transaction to network.

9. Turn off BitKey, disconnect power source, wait 15 minutes to clear RAM

Security guidelines

• Defense in depth: increase security by forcing attackers to overcome a plurality of obstacles.
• Minimize trust: minimize the number of third parties that need to be trusted, and minimize the degree of trust that needs to be placed on the existing trusted parties (e.g., BitKey developers to a degree).
• Minimized complexity: attack surface grows with complexity, so decrease complexity by minimizing number of components, using simpler components (e.g., chromium with webapps)
• Minimum privilege level policy: for example, if a component doesn't need network access, don't give it to it. If a mode doesn't need network access, enforce lack of network access.
• Transparency and verifiability: only use open source components who's integrity can be verified in principle and in which violations of integrity are more likely to be detected.
• Assume and attempt to compensate for human fallibility: avoid assuming users are advanced Bitcoin and security experts. Do the most to protect them from natural mistakes and lack of awareness with more secure defaults, friendly reminders, health warnings, tools for verifying against mistakes.

See README in source code for specifics.

How to build from source

BitKey is built with TKLDev, the TurnKey GNU/Linux build system.

1. Deploy TKLDev (e.g., as a local VM)

2. SSH into TKLDev, clone bitkey git repo and run make:

   
           ssh tkldev
   
           cd products
           git-clone https://github.com/bitkey/bitkey
   
           cd bitkey
           make        
   
           

You're done, enjoy your new BitKey ISO file:

        
        ls -la build/product.iso 
        -rw-r--r-- 1 root root 466616320 Jan 17 21:46 build/product.iso