diff --git a/docs/animated-captcha.gif b/docs/animated-captcha.gif new file mode 100644 index 0000000..c94e5a7 Binary files /dev/null and b/docs/animated-captcha.gif differ diff --git a/docs/bk-setup-tab.png b/docs/bk-setup-tab.png new file mode 100644 index 0000000..3adf03d Binary files /dev/null and b/docs/bk-setup-tab.png differ diff --git a/docs/cc-setup-tab.png b/docs/cc-setup-tab.png new file mode 100644 index 0000000..e83731f Binary files /dev/null and b/docs/cc-setup-tab.png differ diff --git a/docs/index.md b/docs/index.md index 1ec026f..2a571c6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,9 +1,10 @@ -# CK Bunker +# CKBunker ![Screen Shot of CKBunker](screen-shot.jpg) - [CKBunker preview screencast (youtube)](https://www.youtube.com/watch?v=0bHhZbYOiSM) - [Usage examples](examples.md) for HSM/CKBunker. +- [Documentation Website](https://ckbunker.com) - [Github for CKBunker](https://github.com/Coldcard/ckbunker). ## What is the Coinkite Bunker? @@ -115,18 +116,20 @@ the socks proxy of tord (port 9050) will also be used. You will need: - this code -- a Mk3 Coldcard connected via USB +- a Mk3 Coldcard connected via USB, running + [firmware version 3.1.0 or later](https://coldcardwallet.com/docs/upgrade) - `tord` (Tor program) -- Internet connection +- 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? Sorry no. CK Bunker only works on Mk3 because we need the extra RAM -and the newer features of the 608a secure element. +and the newer features of the 608 secure element. ### What is HSM? diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..47226ee --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,123 @@ +# Setup of Your CKBunker + +Step 1 is to install the bunker code and get it running. + +Once it's running, use any ordinary browser to connect to: + + http://localhost:9823/setup + +At this point, you should be focused on the two tabs "Coldcard Setup" +and "Bunker Setup" tabs. + +## Coldcard Setup tab + +![Coldcard Setup screen shot](cc-setup-tab.png) + +"Coldcard Setup" is devoted to creating an HSM spending policy. These settings +are held in a JSON file to be uploaded and confirmed on the Coldcard. + +Typically the Bunker will send the file to the Coldcard when you +press "Save & Start Policy" but you have the option of downloading +the file, and/or importing the JSON file before that point. This is useful if you +want to hand-edit the data, or keep a backup/restore a backup. When you +send the file to the Coldcard, your browser will download a copy of the file, +if the checkbox "Download (sanitized) copy" is set. This version of the policy +file will have the following sensitive fields stripped out: + +- `boot_to_hsm` - unlock code for +- `set_sl`, `allow_sl` - details of the storage locker + +Continue reading [here for details about HSM rules and policy.](rules.md) + +### Using Coldcard Setup _without_ a Coldcard + +By using the "Download Policy" button you can use the pretty web +interface to build your policy file without using any other part +of the CKBunker. In fact a Coldcard does not need to be connected. + +The only limitation of this mode is the _Users_ section. It communicates +directly with the Coldcard to read the list of users and add/remove them. +If you are using those features, you may need to edit the JSON. + +If you use the Bunker to upload your policy, the `allow_sl` and +`set_sl` fields will be overriden by the Bunker and replaced. You +can use `ckcc hsm-start file.json` to upload the JSON policy file, +and start HSM mode on the command line. + +## Bunker Setup tab + +![Bunker Setup screen shot](bk-setup-tab.png) + +There are only a few settings for the Bunker itself: + +- Enable or disable Tor Hidden Service: Once enabled, you may + generate a different onion address by picking "Spin Again". + +- Master Login password: this password is needed to get in to the CKBunker + over the Tor network. There are no usernames. Cannot be shorter than 4 characters. + +- Simple captcha: on the login form, there are two possible styles of captcha. + + - Simple Captcha + + ![simple captcha](simple-captcha.png) + + - Animated Captcha + + ![animated captcha](animated-captcha.gif) + +- "Allow Bunker to be restarted without requiring a restart of the Coldcard": + This setting should be configured before you save and apply your HSM policy + on the "Coldcard Setup" page. It controls the number `allow_sl` inside + the policy, and sets that value to `1` or `13`. If it's `1`, then the + Coldcard will allow only a single read of the Storage Locker, and the + effect of that is the CKBunker can only be reset/started once without + knowing the PIN of the Coldcard. + +### How Bunker Settings are Saved + +In our security model, we assume the CKBunker may be "captured" by +your adversaries. The CKBunker is not the last line of defense---that's the Coldcard +and your HSM policy. + +If the Bunker is captured while it is turned on and running, then +in the worst case, the attackers can read all of main memory, and +will get the Tor Hidden service private key. This will allow them +to impersonate your Bunker in the future. Presumably they can view +your PSBT file and all other web interactions while you work with the Bunker. + +However, they cannot change the HSM policy of the Coldcard. They +do not know the TOTP/2FA secrets, and cannot generate OTP codes +(only the Coldcard knows those) and so they cannot authorize spending +that way and impersonate users. + +When the data associated with the Bunker is "at rest", meaning the +system is not running, we have good protections in place. All Bunker +settings are saved to `./data` directory, as encrypted files. The +name of the file is a hash of the private key, and the contents are +a NaCl secret box (Curve25519). We store the private key for that +file on the Coldcard itself, in the storage locker. + +When the Bunker starts, it searchs for a Coldcard on USB (and it also +looks for the simulator). If it finds one already in HSM mode, then +it reads the storage locker and uses the NaCl private key (32 bytes) +to select and open the corresponding Bunker settings file. Therefore, +each Coldcard has it's own settings for the Bunker. + +Before a Coldcard is connected, or before the policy is saved for +the first time, the settings are held with a fixed key, and end up +in file: `data/bp-1850f665aa1e22c0.dat` based on that key. At the +point where you upload a new policy to a Coldcard, a new key is +picked and added to the policy file. Data on disk at that point is +re-encrypted and moved over. + + +#### Other Notes + +- PSBT files are never saved to disk. They stay in-memory only. +- HSM Policy files are not saved to disk, except as part of the settings. +- If you don't choose _Privacy over UX_ then many key details of your HSM + policy are captured and saved into the encrypted settings. This includes details +like the HSM text summary, user names, and other details that are know only +when the policy is created. + diff --git a/docs/simple-captcha.png b/docs/simple-captcha.png new file mode 100644 index 0000000..756372e Binary files /dev/null and b/docs/simple-captcha.png differ diff --git a/templates/navpage.html b/templates/navpage.html index e84831d..628e2b4 100644 --- a/templates/navpage.html +++ b/templates/navpage.html @@ -12,8 +12,10 @@ {{title}} {% endfor %} - Docs   + Github