diff --git a/README.md b/README.md index 575f29b..3775e74 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,8 @@ ![Screen Shot of CKBunker](docs/screen-shot.jpg) - [Preview screencast (youtube)](https://www.youtube.com/watch?v=0bHhZbYOiSM) -- [Documentation](https://ckbunker.com) +- [Documentation (pretty)](https://ckbunker.com) +- [Documentation (github)](docs/index.md) - [Usage examples and ideas](docs/examples.md) for HSM/CKBunker. diff --git a/docs/hacking.md b/docs/hacking.md index 0cbf483..4f4a130 100644 --- a/docs/hacking.md +++ b/docs/hacking.md @@ -63,13 +63,13 @@ your Coldcard's wallets. # Code Submission Guidelines -PR's are accepted but... +PR's are welcome but... - Please think of other users: don't remove existing use cases. - Don't add weird dependancies if easy to avoid. - Try to match existing coding style. - Large diffs are hard to accept with security-sensitive projects like this. -- Please start your own fork and own it... we love that too! +- Feel free to start your own fork and own it... we love that too! diff --git a/docs/index.md b/docs/index.md index 1920afc..dde405d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,8 +7,15 @@ - [Documentation Website](https://ckbunker.com) - [Github for CKBunker](https://github.com/Coldcard/ckbunker). psbt.md -- Full docs: [Setup Your Bunker](setup.md), [HSM Policy](policy.md), [PSBT Signing](psbt.md), - [Message Signing](msg-signing.md), [Contributing Code](hacking.md) + +## Full Documentation + +1. [Installation](install.md) +2. [Setup Bunker](setup.md) +2. [HSM Policy](policy.md) +2. [PSBT Signing](psbt.md) +2. [Message Signing](msg-signing.md) +2. [Contributing Code](hacking.md) ## What is the Coinkite Bunker? @@ -42,91 +49,6 @@ Learn more about the [Coldcard HSM-related features](https://coldcardwallet.com/ [Follow @COLDCARDwallet on Twitter](https://twitter.com/coldcardwallet) to keep up with the latest updates and security alerts. -## Check-out and Setup - -Do a checkout, recursively to get all the submodules: - - git clone --recursive https://github.com/Coldcard/ckbunker.git - -Then: - -- `virtualenv -p python3 ENV` (Python 3.7 or higher is required) -- `source ENV/bin/activate` (or `source ENV/bin/activate.csh` based on shell preference) -- `pip install -r requirements.txt` -- `pip install --editable .` - -## Usage - -The executable is called `ckbunker`: - -```sh -$ ckbunker --help -Usage: ckbunker [OPTIONS] COMMAND [ARGS]... - -Options: - -s, --serial HEX Operate on specific unit (default: first found) - --help Show this message and exit. - -Commands: - list List all attached Coldcard devices - example Show an example config file, using the default values - run Start the CKBunker for normal operation - setup Configure your transaction signing policy, install it and then... -``` - -There are two modes for the Bunker: "setup" and "run mode". In setup -mode, Tor connections are disabled, as is the login screen. There is no -security and it's meant for initial setup of the Coldcard and Bunker. - -You would typically use the setup mode for picking the onion address, the -master login password and all the details of the HSM policy. - -```sh -$ ckbunker setup -``` - -Open this URL in your local web browser (must be same machine): - - -Once the Coldcard is running in HSM mode, with your policy installed, -it makes sense to operate in normal "run" mode. This enables a simple -login screen to keep out visitors: - -```sh -$ ckbunker run -``` - -You may also run with remote connections (and login) disabled. This would be useful -if you have some existing web proxy already in place. - -```sh -$ ckbunker --local run -``` - -## Tor Use - -To access over Tor as a hidden service, you must have `tord` running -on the same machine. For desktop systems, keeping TorBrowser open -is enough to acheive this. On servers, start tord with default options, -and ckbunker will use the control port (localhost port 9051 or 9151). - -If you use the bunker to broadcast the final (signed) transaction, -the socks proxy of tord (port 9050) will also be used. - - -## Operational Requirements - -You will need: - -- this code -- a Mk3 Coldcard connected via USB, running - [firmware version 3.1.0 or later](https://coldcardwallet.com/docs/upgrade) -- `tord` (Tor program) -- an Internet connection -- a Tor-capable browser, like "Tor Browser" or Tails. -- (optional) a microSD card, for logging of transactions on Coldcard -- (optional, recommended) a mobile phone with TOTP 2FA app, like Google Authenticator or FreeOTP - ## FAQ ### Will HSM mode be supported on Mk1 or Mk2? diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..b487027 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,129 @@ +# Installation + +## Check-out and Setup + +Do a checkout, recursively to get all the submodules: + + git clone --recursive https://github.com/Coldcard/ckbunker.git + +Then: + +- `virtualenv -p python3 ENV` (Python 3.7 or higher is required) +- `source ENV/bin/activate` (or `source ENV/bin/activate.csh` based on shell preference) +- `pip install -r requirements.txt` +- `pip install --editable .` + +## Operational Requirements + +You will need: + +- this code (see above) +- a Mk3 Coldcard connected via USB, running + [firmware version 3.1.0 or later](https://coldcardwallet.com/docs/upgrade) +- `tord` (Tor program) +- an Internet connection +- a Tor-capable browser, like "Tor Browser" or Tails. +- (optional) a microSD card, for logging of transactions on Coldcard +- (optional, recommended) a mobile phone with TOTP 2FA app, like Google Authenticator or FreeOTP + +## Usage + +The executable is called `ckbunker`: + +```sh +$ ckbunker --help +Usage: ckbunker [OPTIONS] COMMAND [ARGS]... + +Options: + -s, --serial HEX Operate on specific unit (default: first found) + --help Show this message and exit. + +Commands: + list List all attached Coldcard devices + example Show an example config file, using the default values + run Start the CKBunker for normal operation + setup Configure your transaction signing policy, install it and then... +``` + +There are two modes for the Bunker: "setup" and "run mode". In setup +mode, Tor connections are disabled, as is the login screen. There is no +security and it's meant for initial setup of the Coldcard and Bunker. + +You would typically use the setup mode for picking the onion address, the +master login password and all the details of the HSM policy. + +```sh +$ ckbunker setup +``` + +Open this URL in your local web browser (must be same machine): + + +Once the Coldcard is running in HSM mode, with your policy installed, +it makes sense to operate in normal "run" mode. This enables a simple +login screen to keep out visitors: + +```sh +$ ckbunker run +``` + +You may also run with remote connections (and login) disabled. This would be useful +if you have some existing web proxy already in place. + +```sh +$ ckbunker --local run +``` + +## Tor Use + +To access over Tor as a hidden service, you must have `tord` running +on the same machine. For desktop systems, keeping TorBrowser open +is enough to acheive this. On servers, start tord with default options, +and ckbunker will use the control port (localhost port 9051 or 9151). + +If you use the bunker to broadcast the final (signed) transaction, +the socks proxy of tord (port 9050) will also be used. + + + +## Other Command Line Options + +```sh +% ckbunker run --help +Usage: ckbunker run [OPTIONS] + + Start the CKBunker for normal operation + +Options: + -l, --local Don't enable Tor (onion) access: just be on localhost + -f, --psbt filename.psbt Preload first PSBT to be signed + -c, --config-file FILENAME + --help Show this message and exit. + +``` + +You can specify a PSBT file for immediate use. That file will be "uploaded" +and be ready to sign, but the system operates normally from there. You can +upload further PSBT files and so on. + +```sh +% ckbunker setup --help +Usage: ckbunker setup [OPTIONS] + + Configure your transaction signing policy, install it and then operate. + +Options: + -l, --local Don't enable Tor (onion) access: just be on localhost + -c, --config-file FILENAME + --help Show this message and exit. +``` + +Both forms take an optional config file. It's simple YAML and allows +you to change the web server port number and similar values. +The values that can be configured are defined in `persist.py` in +the `Settings` class. See also `example-settings.yaml`. + + +# Next Steps + +[Bunker setup](setup.md)