From 5e42d3d696051020f1094667ddaca67ce928fae1 Mon Sep 17 00:00:00 2001 From: Andrew Chow Date: Fri, 8 Mar 2019 15:20:18 -0500 Subject: [PATCH 1/6] Rename to Hardware Wallet Interface and describe it a bit more --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 16e0bd4..d36c3c8 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ -# Bitcoin Hardware Wallet Interaction scripts +# Bitcoin Hardware Wallet Interface [![Build Status](https://travis-ci.org/bitcoin-core/HWI.svg?branch=master)](https://travis-ci.org/bitcoin-core/HWI) -This project contains several scripts for interacting with Bitcoin hardware wallets. +The Bitcoin Hardware Wallet Interface is a Python library and command line tool for interacting with hardware wallets. +It provides a standard way for software to work with hardware wallets without needing to implement device specific drivers. +Python software can use the provided library (`hwilib`). Software in other languages can execute the `hwi` tool. ## Prerequisites From fc33fc5bbeaad73bbaeb0005141883b20612aada Mon Sep 17 00:00:00 2001 From: Andrew Chow Date: Fri, 8 Mar 2019 15:20:31 -0500 Subject: [PATCH 2/6] List additional dependencies --- README.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d36c3c8..0cdc4d6 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,26 @@ Python software can use the provided library (`hwilib`). Software in other langu ## Prerequisites -Python 3 is required. The libraries and udev rules for each device must also be installed. +Python 3 is required. The libraries and udev rules for each device must also be installed. Some libraries will need to be installed -Install all of the libraries using `pip` (in virtualenv or system): +For Ubuntu/Debian: +``` +sudo apt install libusb-1.0-0-dev libudev-dev +``` + +For macOS: +``` +brew install libusb +``` + +This project uses the [Poetry](https://github.com/sdispater/poetry) dependency manager. +Once HWI's source has been downloaded with git clone, it and its dependencies can be installed via poetry by execting the following in the root source directory: + +``` +poetry install +``` + +Pip can also be used to install all of the dependencies (in virtualenv or system): ``` pip3 install hidapi # HID API needed in general From b7873acddc9224a94cf247d336b3f0a178c00140 Mon Sep 17 00:00:00 2001 From: Andrew Chow Date: Fri, 8 Mar 2019 15:46:46 -0500 Subject: [PATCH 3/6] Describe the other files in contrib/ --- contrib/README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/contrib/README.md b/contrib/README.md index f484e2d..b92d5fd 100644 --- a/contrib/README.md +++ b/contrib/README.md @@ -19,3 +19,17 @@ Sets up Wine with Python and everything needed to build Windows binaries. Create ## `generate_setup.sh` Builds the source distribution and extracts the setup.py from it. + +## `build.Dockerfile` + +A Dockerfile for setting up the deterministic build environment. + +# Other files + +## `reproducible-python.diff` + +A path for python in order to do a deterministic build of Python for the deterministically built binaries. + +## `pyinstaller-hooks/hook-hwilib.devices.py` + +Pyinstaller hook so that the device drivers are actually included. Due to how the imports work, we need this hook. From 7929692c9daaf8b7d1117f35f3e7c39d185735fd Mon Sep 17 00:00:00 2001 From: Andrew Chow Date: Fri, 8 Mar 2019 15:47:00 -0500 Subject: [PATCH 4/6] Update Bitcoin Core usage docs to match current software behavior --- docs/bitcoin-core-usage.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/bitcoin-core-usage.md b/docs/bitcoin-core-usage.md index 4a3d88c..132e18b 100644 --- a/docs/bitcoin-core-usage.md +++ b/docs/bitcoin-core-usage.md @@ -1,6 +1,6 @@ # Using Bitcoin Core with Hardware Wallets -This approach is fairly manual, requires the command line, and requires a patched version of Bitcoin Core. +This approach is fairly manual, requires the command line, and Bitcoin Core >=0.18.0. Note: For this guide, code lines prefixed with `$` means that the command is typed in the terminal. Lines without `$` are output of the commands. @@ -14,14 +14,14 @@ We are not liable for any coins that may be lost through this method. The softwa This method of using hardware wallets uses Bitcoin Core as the wallet for monitoring the blockchain. It allows a user to use their own full node instead of relying on an SPV wallet or vendor provided software. -HWI works with Bitcoin Core as of commit [c576979b78b541bf3b4a7cbeee989b55d268e3e1](https://github.com/bitcoin/bitcoin/commit/c576979b78b541bf3b4a7cbeee989b55d268e3e1). +HWI works with Bitcoin Core as of commit [c576979b78b541bf3b4a7cbeee989b55d268e3e1](https://github.com/bitcoin/bitcoin/commit/c576979b78b541bf3b4a7cbeee989b55d268e3e1). It is usable with Bitcoin Core >=0.18.0. ## Setup -Clone the modified Bitcoin Core and build it. Clone HWI. +Clone Bitcoin Core and build it. Clone HWI. ``` -$ git clone https://github.com/achow101/bitcoin.git -b hww +$ git clone https://github.com/bitcoin/bitcoin.git $ cd bitcoin $ ./autogen.sh $ ./configure @@ -47,7 +47,7 @@ We will be fetching keys at the BIP 84 default. ``` $ ./hwi.py -f 8038ecd9 getkeypool --wpkh --keypool 0 1000 -[{"desc": "wpkh([8038ecd9/84h/0h/0h]xpub6DR4rqx16YnCcfwFqgwvJdKiWrjDRzqxYTY44aoyHwZDSeSB5n2tqt42aYr9qPKhSKUdftPdTjhHrKKD6WGKVbuyhMvGH76VyKKZubg8o4P/0/*)", "internal": false, "range": {"start": 0, "end": 1000}, "timestamp": "now", "keypool": true, "watchonly": true}] +[{"desc": "wpkh([8038ecd9/84h/0h/0h]xpub6DR4rqx16YnCcfwFqgwvJdKiWrjDRzqxYTY44aoyHwZDSeSB5n2tqt42aYr9qPKhSKUdftPdTjhHrKKD6WGKVbuyhMvGH76VyKKZubg8o4P/0/*)#36sal9a4", "internal": false, "range": [0, 1000], "timestamp": "now", "keypool": true, "watchonly": true}] ``` We now create a new Bitcoin Core wallet and import the keys into Bitcoin Core. The output is formatted properly for Bitcoin Core so it can be copy and pasted. @@ -58,7 +58,7 @@ $ ../bitcoin/src/bitcoin-cli createwallet "coldcard" true "name": "coldcard", "warning": "" } -$ ../bitcoin/src/bitcoin-cli -rpcwallet=coldcard importmulti '[{"desc": "wpkh([8038ecd9/84h/0h/0h]xpub6DR4rqx16YnCcfwFqgwvJdKiWrjDRzqxYTY44aoyHwZDSeSB5n2tqt42aYr9qPKhSKUdftPdTjhHrKKD6WGKVbuyhMvGH76VyKKZubg8o4P/0/*)", "internal": false, "range": {"start": 0, "end": 1000}, "timestamp": "now", "keypool": true, "watchonly": true}]' +$ ../bitcoin/src/bitcoin-cli -rpcwallet=coldcard importmulti '[{"desc": "wpkh([8038ecd9/84'/0'/0']xpub6DR4rqx16YnCcfwFqgwvJdKiWrjDRzqxYTY44aoyHwZDSeSB5n2tqt42aYr9qPKhSKUdftPdTjhHrKKD6WGKVbuyhMvGH76VyKKZubg8o4P/0/*)#36sal9a4", "internal": false, "range": [0, 1000], "timestamp": "now", "keypool": true, "watchonly": true}]' [ { @@ -71,8 +71,8 @@ Now we repeat the `getkeypool` and `importmulti` steps but set a `--internal` fl ``` $ ./hwi.py -f 8038ecd9 getkeypool --wpkh --keypool --internal 0 1000 -[{"internal": true, "timestamp": "now", "desc": "wpkh([8038ecd9/84h/0h/0h]xpub6DR4rqx16YnCcfwFqgwvJdKiWrjDRzqxYTY44aoyHwZDSeSB5n2tqt42aYr9qPKhSKUdftPdTjhHrKKD6WGKVbuyhMvGH76VyKKZubg8o4P/1/*)", "keypool": true, "range": {"start": 0, "end": 1000}}] -$ ../bitcoin/src/bitcoin-cli -rpcwallet=coldcard importmulti '[{"internal": true, "timestamp": "now", "desc": "wpkh([8038ecd9/84h/0h/0h]xpub6DR4rqx16YnCcfwFqgwvJdKiWrjDRzqxYTY44aoyHwZDSeSB5n2tqt42aYr9qPKhSKUdftPdTjhHrKKD6WGKVbuyhMvGH76VyKKZubg8o4P/1/*)", "keypool": true, "range": {"start": 0, "end": 1000}, "watchonly": true}]' +[{"internal": true, "timestamp": "now", "desc": "wpkh([8038ecd9/84h/0h/0h]xpub6DR4rqx16YnCcfwFqgwvJdKiWrjDRzqxYTY44aoyHwZDSeSB5n2tqt42aYr9qPKhSKUdftPdTjhHrKKD6WGKVbuyhMvGH76VyKKZubg8o4P/1/*)#qw4uzsdd", "keypool": true, "range": {"start": 0, "end": 1000}}] +$ ../bitcoin/src/bitcoin-cli -rpcwallet=coldcard importmulti '[{"internal": true, "timestamp": "now", "desc": "wpkh([8038ecd9/84h/0h/0h]xpub6DR4rqx16YnCcfwFqgwvJdKiWrjDRzqxYTY44aoyHwZDSeSB5n2tqt42aYr9qPKhSKUdftPdTjhHrKKD6WGKVbuyhMvGH76VyKKZubg8o4P/1/*)", "keypool": true, "range": [0, 1000], "watchonly": true}]' [ { @@ -90,8 +90,8 @@ Here are some examples (`` refers to a block height before the wall $ ../bitcoin/src/bitcoin-cli rescanblockchain $ ../bitcoin/src/bitcoin-cli rescanblockchain 500000 # Rescan from block 500000 -$ ../bitcoin/src/bitcoin-cli -rpcwallet=coldcard importmulti '[{"internal": true, "timestamp": , "desc": "wpkh([8038ecd9/84h/0h/0h]xpub6DR4rqx16YnCcfwFqgwvJdKiWrjDRzqxYTY44aoyHwZDSeSB5n2tqt42aYr9qPKhSKUdftPdTjhHrKKD6WGKVbuyhMvGH76VyKKZubg8o4P/1/*)", "keypool": true, "range": {"start": 0, "end": 1000}, "watchonly": true}]' -$ ../bitcoin/src/bitcoin-cli -rpcwallet=coldcard importmulti '[{"internal": true, "timestamp": 500000, "desc": "wpkh([8038ecd9/84h/0h/0h]xpub6DR4rqx16YnCcfwFqgwvJdKiWrjDRzqxYTY44aoyHwZDSeSB5n2tqt42aYr9qPKhSKUdftPdTjhHrKKD6WGKVbuyhMvGH76VyKKZubg8o4P/1/*)", "keypool": true, "range": {"start": 0, "end": 1000}, "watchonly": true}]' # Imports and rescans from block 500000 +$ ../bitcoin/src/bitcoin-cli -rpcwallet=coldcard importmulti '[{"internal": true, "timestamp": , "desc": "wpkh([8038ecd9/84h/0h/0h]xpub6DR4rqx16YnCcfwFqgwvJdKiWrjDRzqxYTY44aoyHwZDSeSB5n2tqt42aYr9qPKhSKUdftPdTjhHrKKD6WGKVbuyhMvGH76VyKKZubg8o4P/1/*)#qw4uzsdd", "keypool": true, "range": [0, 1000], "watchonly": true}]' +$ ../bitcoin/src/bitcoin-cli -rpcwallet=coldcard importmulti '[{"internal": true, "timestamp": 500000, "desc": "wpkh([8038ecd9/84h/0h/0h]xpub6DR4rqx16YnCcfwFqgwvJdKiWrjDRzqxYTY44aoyHwZDSeSB5n2tqt42aYr9qPKhSKUdftPdTjhHrKKD6WGKVbuyhMvGH76VyKKZubg8o4P/1/*)#qw4uzsdd", "keypool": true, "range": [0, 1000], "watchonly": true}]' # Imports and rescans from block 500000 ``` ## Usage From 0235baf3777b5b10665e48d076006732097bcfe1 Mon Sep 17 00:00:00 2001 From: Andrew Chow Date: Fri, 8 Mar 2019 15:49:40 -0500 Subject: [PATCH 5/6] List all command support --- docs/digitalbitbox.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/digitalbitbox.md b/docs/digitalbitbox.md index e61c3b6..1c83efe 100644 --- a/docs/digitalbitbox.md +++ b/docs/digitalbitbox.md @@ -12,6 +12,7 @@ Current implemented commands are: - `restore` - `backup` - `displayaddress` +- `signmessage` ## Usage Notes From 376245ae0f8547d4999dbd0a8efc48ffc043e340 Mon Sep 17 00:00:00 2001 From: Andrew Chow Date: Fri, 8 Mar 2019 15:58:34 -0500 Subject: [PATCH 6/6] Update tests documentation with new tests --- test/README.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/test/README.md b/test/README.md index 0b59ec7..51a90ee 100644 --- a/test/README.md +++ b/test/README.md @@ -10,19 +10,22 @@ This is taken directly from the [python reference implementation](https://github It implements all of the [BIP 174 serialization test vectors](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#Test_Vectors). - `test_trezor.py` tests the command line interface and the Trezor implementation. It uses the [Trezor One firmware emulator](https://github.com/trezor/trezor-mcu/#building-for-development). -It also tests usage with `bitcoind`, so the [patched Bitcoin Core](../docs/bitcoin-core-usage.md#bitcoin-core) is required. +It also tests usage with `bitcoind`. +- `test_keepkey.py` tests the command line interface and the Keepkey implementation. +It uses the [Keepkey firmware emulator](https://github.com/keepkey/keepkey-firmware/blob/master/docs/Build.md). +It also tests usage with `bitcoind`. - `test_coldcard.py` tests the command line interface and Coldcard implementation. It uses the [Coldcard simulator](https://github.com/Coldcard/firmware/tree/master/unix#coldcard-desktop-simulator). -It also tests usage with `bitcoind`, so the [patched Bitcoin Core](../docs/bitcoin-core-usage.md#bitcoin-core) is required. +It also tests usage with `bitcoind`. -`setup_environment.sh` will build the Trezor emulator, the Coldcard simulator, and the patched `bitcoind`. -if run in the `test/` directory, these will be built in `work/test/trezor-mcu`, `work/test/firmware`, and `work/test/bitcoin` respectively. +`setup_environment.sh` will build the Trezor emulator, the Coldcard simulator, the Keepkey emulator, the Digital Bitbox simulator, and `bitcoind`. +if run in the `test/` directory, these will be built in `work/test/trezor-mcu`, `work/test/firmware`, `work/test/keepkey-firmware`, `work/test/mcu`, and `work/test/bitcoin` respectively. -`run_tests.py` runs the tests. If run from the `test/` directory, it will be able to find the Trezor emulator, Coldcard simulator, and bitcoind. +`run_tests.py` runs the tests. If run from the `test/` directory, it will be able to find the Trezor emulator, Coldcard simulator, Keepkey emulator, Digital Bitbox simulator, and bitcoind. Otherwise the paths to those will need to be specified on the command line. -test_trezor.py` and `test_coldcard.py` can be disabled. +test_trezor.py`, `test_coldcard.py`, `test_keepkey.py`, and `test/test_digitalbitbox.py` can be disabled. -If you are building the Trezor emulator, the Coldcard simulator, and `bitcoind` without `setup_environment.sh`, then you will need to make `work/` inside of `test/`. +If you are building the Trezor emulator, the Coldcard simulator, the Keepkey emulator, the Digital Bitbox simulator, and `bitcoind` without `setup_environment.sh`, then you will need to make `work/` inside of `test/`. ``` $ cd test