BitKey is a swiss army knife of handy Bitcoin tools built on top of Debian, which we created to scratch our own itch.
Community Branch
As most would be aware, BitKey is a side project of @turnkeylinux. Other than the initial development and a few updates here and there over the years, we've done a really poor job of maintaining it! :'(
However, the BitKey community was lucky enough that @estevaocm has come along and given the project some love! Seeing as we're doing such a poor job and he's doing such a great one, we've asked him to take over as community leader and maintain this community branch of the offical BitKey repo.
The master branch remains the "offical" BitKey release branch, but for the foreseeable future, the "community" branch will be the one you'll most likely want to use! Community ISOs (built and published by @estevaocm) should be avaialble from the releases area of this repo.
Backstory
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.
We used the TurnKey GNU/Linux build system to create a self-contained read-only CD/USB stick to satisfy all our Bitcoin needs. Yours too we hope, and if not we're open to suggestions for improvement.
In December 2017, the project was forked to update all software and include webcam support for QR code scanning and additional altcoin wallets.
In March 2018, @estevaocm has graciously agreed to lead maintence of this communtiy branch. His work to date has been merged from his fork, back into this branch.
Apps: batteries included!
Apps that are allowed network access in online mode:
- Electrum with wrapper that stores wallet on a USB in a LUKS encrypted loopback filesystem. During creation, displays passphrase strength estimates such as entropy and crack time.
- Electrum-LTC for Litecoin (with wrapper)
- Electron-Cash for Bitcoin Cash (with wrapper)
- Electrum-DASH for DASH (with wrapper)
- Armory Wallet (with wrapper)
- QtQR: allows QR code scanning from webcam
- zbar-tools: alternative for QtQR
- Exodus: multi-coin wallet, including ShapeShift exchanging (NOT OPEN SOURCE)
- CryptoSeed: encryption for paper wallets
- KeePassXC: password manager
- Online Web apps:
- MyEtherWallet
- Ripple Wallet
- Minimalistic Ripple Wallet
- Coinb.in: swiss army knife of bitcoin tools
Offline Web apps (not allowed network access even in online mode):
- Base43 decoder: decodes the strings from Electrum QR codes
- BIP39 Mnemonic Code Converter: paper wallet seeds for 30+ cryptocurrencies (BIP39, BIP32, BIP44, BIP49, BIP84, BIP141)
- bitaddress: paper wallet generator
- bitcoinpaperwallet: paper wallet generator
- IOTA paper wallet
- IOTA seed generator
- Monero paper wallet
- qrcode generator: encodes anything as a qrcode
- warpwallet: brainwallet with strong KDF (scrypt+pbkdf2) and salt
- zxcvbn: realistic password strength estimator
Advanced tools for Bitcoin ninjas:
- bx: the Bitcoin command line tool (AKA libbitcoin-explorer)
Other:
- Chromium web browser: runs in incognito mode by default (only visible in online mode), updated beyond default Debian Jessie
- Network manager
- Printer manager
- File manager
- Text editor
Installing BitKey on a USB stick or CDROM
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. Also loads the system much faster.
On USB sticks without write protection, you can remove BitKey USB after booting as an additional security measure. BitKey loads into RAM so after booting you no longer need the USB.
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
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
Formatting your 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:
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
Reformat the drive:
$ sudo mkfs.vfat /dev/sda1 mkfs.fat 3.0.27 (2014-11-12)
Usage modes
See https://bitkey.io for a detailed introduction and usage guide.
BitKey Live CD/USB supports three modes of operation selected from a boot time menu.
High security - Cold storage boot modes
Two cold storage modes:
cold-offline: create wallet, sign transactions
In this mode, the desktop background is green (mnemonic for cool and safe)
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.
Attention: cold-online mode has been disabled due to no longer being supported by Electrum 3. So your wallet's master public key must be manually exported to a cold-online wallet. It may be most convenient to generate the QR code for the master public key, then scan it from the Electrum app for Android to create a watch-only wallet. The watch-only wallet allows you to check your balance and history, prepare and broadcast transactions, but not sign transactions. If you only ever sign your transactions in cold-offline mode and never otherwise compromise your secret master private key, your funds cannot be stolen by a network attack. Since this version of Bitkey includes webcam support, you may use the cam to scan the QR code of the prepared transaction for signing, thus never exposing Bitkey or your wallet to harmful files. For more information, refer to http://docs.electrum.org/en/latest/coldstorage.html
Medium security - Hot-online boot mode (red background)
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 - Jason Bourne mode
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.
Inspired by how Jason Bourne stores his Bitcoin:
http://maxtaco.github.io/bitcoin/2014/01/16/how-jason-bourne-stores-his-bitcoin/
Generating wallet step
- Boot BitKey in cold-offline mode, remove BitKey USB
- Generate Warpwallet with a strong passphrase and your e-mail as salt
- Save public Bitcoin address (e.g., scan qrcode)
- 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.
Safety warning regarding salts: do not use Warpwallet without a salt. You're not going to forget your e-mail and using a salt makes attacks vastly more difficult.
Public Service Announcement regarding Warpwallet passphrases:
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.
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.
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:
Boot BitKey in cold-online mode, remove BitKey USB
Restore watch-only wallet and run Electrum, from command line:
$ electrum restore $PUBLIC_ADDRESS $ electrum
Insert USB stick for storing unsigned transaction
Fill in recipient under Send tab and "Save" unsigned transaction to USB at /media/usb/
Shutdown/Reboot BitKey
Signing transaction step
Boot BitKey in cold-offline mode, remove BitKey USB
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
Unplug USB stick
Use Warpwallet to restore brainwallet private key
Launch Electrum from command line so that it stores wallet in RAM:
$ electrum -w /tmp/brainwallet
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
Create a QRCode for the signed transaction:
- Open Signed transaction in text editor
- Open qrcode app: cut and paste hex of signed transaction
Scan QRCode of signed transaction with phone and broadcast transaction to network.
Turn off BitKey as soon as the QRCode has been scanned, disconnect power source, wait 15 minutes to clear RAM
Desktop usage tips (Keyboard and mouse shortcuts)
Full custom keybindings in overlay/usr/share/glib-2.0/schemas/20_custom.gschema.override
Copy, Cut and Paste
Keyboard: Ctrl+C, CTRL+X and CTRL-V
Mouse:
To copy, click text and drag to highlight text to be copied
To paste, left click to focus keyboard, then middle mouse click to paste. If no middle mouse button exists, clicking both right and left buttons simultaneously also works.
Window management
Window operations:
- Right-click titlebar
- ALT+F3
Split screen window positioning:
Dragging window to left or right
This makes a window neatly fill half the screen
Maximize window by dragging to top of screen
Toggle window maximization:
- double click on window titlebar
- ALT+F10
Minimize window: ALT+F9
Resize window: Alt+F8
Close window with CTRL+W or ALT-F4
Switch between windows (including minimized): Alt+TAB
Workspaces
- Switch workspaces:
- <Win> F1-F4
- <Ctrl> <Alt> Left/Right
- Move window to a different workspace: <Win> <Shift> F1-F4
Security model
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.
Specifics:
Change desktop background color to indicate boot mode
- cold-offline: green background
- cold-online: blue background
- hot-online: red background
Electrum wrapper:
automatically configures default wallet based on boot mode
In cold-offline mode: wallet is stored in an encrypted LUKS, with enforced passphrase complexity. Following offline wallet generation a watch only wallet is created containing only public keys.
In cold-online mode: only the watch wallet is accessible, the wallet containing private keys is inaccessible so that the user is never accidentally prompted for the passphrase and can't open the wallet online by mistake.
In hot-online mode: separate wallet file, so that even if you store the wallets on the same USB key, you can't accidentally open the cold-offline wallet by booting into the wrong mode.
Disabled networking in cold-offline mode: all plan/net network packages are purged on boot by /usr/lib/bitkey.d/purge-packages script
Deny network access to local webapps (e.g., warpwallet, qrcode generator) that don't need it.
Security in depth that prevents even a trojaned version of the app from leaking information to the network, even in online mode on a non airgapped computer.
Webcam enabled for QR code scanning so no physical media communication is required. This allows your private keys to remain perfectly secret, aside from a BIOS attack. You should only communicate through QR codes, no USB drives aside from the one containing the keys. Verify the QR codes' contents at every exchange to make sure no malware is acting.
All included components are open source
Best effort to verify integrity of source components
- do not accept any component without independent verification
- download upstream archives from most authoritative trusted, verifiable source
- check matching hash sums
- verify PGP signatures when signatures are available
- verify authenticity of PGP keys when possible (e.g., using keybase)
- generate and inspect diff from tagged releases
vouch for source components by signing list of signatures:
gpg --verify /usr/local/src/SHA256SUM.asc
How to build from source
BitKey is built with TKLDev, the TurnKey GNU/Linux build system.
Deploy TKLDev (e.g., as a local VM)
SSH into TKLDev and (shallow) clone bitkey git repo:
ssh tkldev cd products git-clone --depth 1 https://github.com/bitkey/bitkey cd bitkey make
Reporting a bug, issue or feature request
The ideal bug/issue includes:
- A detailed description of the issue.
- How to reproduce the issue step by step.
- Any extra information that might be relevant, such as your hardware, network card, boot media, any changes made prior to issue, etc.
The ideal feature request includes:
- A detailed description of feature and component it relates to.
- One or more use cases for the feature.
- Any extra information that might be relevant.
Before creating a new issue on the Issue Tracker, please check to see if a similar issue already exists. If it does, post a comment showing it also affects you. Knowing an issue effects multiple users is useful when we decide how to prioritize limited development resources. Please try and include any additional information you think might help us close the issue.
Contributing as a developer
BitKey, like TurnKey, is 100% free software and the code for all components is right here on GitHub. Developers with good ideas are strongly encouraged to be bold and contribute code. Use the source Luke!
See the guidelines and walk through.