diff --git a/docs/animated-captcha.gif b/docs/img/animated-captcha.gif similarity index 100% rename from docs/animated-captcha.gif rename to docs/img/animated-captcha.gif diff --git a/docs/bk-setup-tab.png b/docs/img/bk-setup-tab.png similarity index 100% rename from docs/bk-setup-tab.png rename to docs/img/bk-setup-tab.png diff --git a/docs/cc-setup-tab.png b/docs/img/cc-setup-tab.png similarity index 100% rename from docs/cc-setup-tab.png rename to docs/img/cc-setup-tab.png diff --git a/docs/simple-captcha.png b/docs/img/simple-captcha.png similarity index 100% rename from docs/simple-captcha.png rename to docs/img/simple-captcha.png diff --git a/docs/img/snap-other-policy.png b/docs/img/snap-other-policy.png new file mode 100644 index 0000000..fe5d7a2 Binary files /dev/null and b/docs/img/snap-other-policy.png differ diff --git a/docs/img/snap-paths.png b/docs/img/snap-paths.png new file mode 100644 index 0000000..1fe8647 Binary files /dev/null and b/docs/img/snap-paths.png differ diff --git a/docs/img/snap-rules.png b/docs/img/snap-rules.png new file mode 100644 index 0000000..89ac58a Binary files /dev/null and b/docs/img/snap-rules.png differ diff --git a/docs/img/snap-users.png b/docs/img/snap-users.png new file mode 100644 index 0000000..ae2d538 Binary files /dev/null and b/docs/img/snap-users.png differ diff --git a/docs/index.md b/docs/index.md index c00f7c5..1920afc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,7 +7,7 @@ - [Documentation Website](https://ckbunker.com) - [Github for CKBunker](https://github.com/Coldcard/ckbunker). psbt.md -- Full docs: [Setup Your Bunker](setup.md), [PSBT Signing](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) ## What is the Coinkite Bunker? diff --git a/docs/policy.md b/docs/policy.md new file mode 100644 index 0000000..e01d70c --- /dev/null +++ b/docs/policy.md @@ -0,0 +1,234 @@ +# HSM Policy Config + +![Coldcard Setup screen shot](img/cc-setup-tab.png) + + +# Spending Rules + +Multiple spending rules can be defined. The system scans the rules +starting from the first one, and will test each rule. The first +rule that is satisfied is applied and following rules are not considered. + +We recommend putting the most narrow rules first. Catch-all rules, which +might move more money should be later in the list. + +By combining multiple rules, with diffent restrictions, it's possible +to create a secure and yet flexible policy. + + +![Spending Rules screen shot](img/snap-rules.png) + + +## Velocity Time Period + +To implement spending limits based on time, the Coldcard requires you to define +a period. This period, expressed in minutes, applies to all rules. Any rule with +a defined "Per-Period Amount" value, will be affected. + +The period starts when it is first used. There is no absolute concept of +time on the Coldcard because it doesn't have a real time clock. There is only one +period, so it will begin as soon as any rule using a velocity limit +is applied successfully. + +At the end of the time period, the totals are reset to zero. + +## Individual Rules + +Each rule consists of these values, which are all considered at the same time. + +- _Max Amount_: max BTC per transaction, that this rule can apply to (independent of period) +- _Per-Period Amount_: total BTC that can move thu this rule in the period +- _Destination Whitelist_: a list of specific addresses which are allowed as destinations +- _Multisig Wallet Name_: either name of a multisig wallet, or + `1` indicating rule only applies to non-multisig wallets. +- _Authorizing Users_: a list of users that are able to approve the transaction (N) +_ _Minimum Users Needed_: number of users (M) needed to approve (from list of users + for this rule, not the system) +- _Local Confirmation Code needed_: a local user must (also) approve (via 6-digits entered on keypad) + +When an element of the rule is has no value, then the restriction +does not apply. For example, if _Destination Whitelist_ is empty, +then the Coldcard will not consider the destination address when +considering the rule. + +If no rules are defined, then no PSBT will be signed. This can be +useful for text message signing applications. On the other hand, +an empty rule, allows any transaction to be signed, so be careful! + +### Max Transaction Amount + +Max amount per transaction is seems less useful because a number of transactions +could be put together to "work around" this rule. However, if there is natural +rate-limiting in your system, for example, by requiring a +local operator to enter a code eeach time, then this is still helpful. + +### Authorizing Users + +You can list username in the `users` field. If defined the `min_users` controls +how many of those are required. By default (if `min_users` isn't defined), all users +listed must confirm the operation. You can achieve 2-of-5 and similar setups +using `min_users`. All users listed must already be defined on the Coldcard +before the policy is activated. + +### Limit to Named Wallet + +The `wallet` field can be omitted, or set to the name of a multisig wallet. If set +to the string `1`, it indicates this rule only applies to the non-multisig wallet. + +### Destination Whitelist + +You may specify a list of addresses in the whitelist field. The Coldcard will +only apply the rule if all destination addresses of the PSBT transaction are +included in the whitelist. This is a powerful feature when your target wallets +that you control, such as emergency cold wallets. + + + +# User Management + +![user management](img/snap-users.png) + + +To support use of the Coldcard in HSM mode, the Coldcard can hold +usernames and their shared secrets for authentication purposes. At +present, this is only useful for use in HSM mode. The user's login +data (secrets) are stored exclusively on the Coldcard, and are never +stored in the CKBunker. + +Two methods are offered: shared password (ie. classic "something +you know") or TOTP (time-based one-time pass) 2FA authentication, +compatible with [RFC6238](https://tools.ietf.org/html/rfc6238). Most +people will already have an app on their mobile phone to hold +the shared secrets and simplify the number-calculating process. + +Creating new users can **only** be done over USB protocol with the +help of CKBunker or `ckcc` programs. However, once the user is +established, you may view it and remove them from the menu system +on the Coldcard, in the Advanced menu, under "User Management". + +The best practice is for the Coldcard to generate the password or +TOTP secret and display it on-screen in a QR code. If you are using +a TOTP app, such as Google Authenticator or FreeOTP, then you can +scan the screen of the Coldcard to install the code. Unfortunately, +due to limited screen space, there isn't room for the meta data +such as username or specific Coldcard number: your app will only +show "CC". + +It is possible to send a user-provided password over USB, in which +case, the QR code is not shown. This requires trust of the attached +computer during this operation, and so we do not recommend it. + +Click the (X) beside a username to remove it. This will invalid your +HSM policy if that user is involved with a rule. You'll need to change +the rule, or create a new user with the old name. + + +# Derivation Paths + +This section controls message signing and derivation paths allowed for +sharing addresses and derived xpubs. + +![derivation paths](img/snap-paths.png) + +## Message Signing + +To enable text message signing, list one or more BIP32 derivation paths in this section. +You can use the special value `any` to allow all signing. You may also use a star +in the last position of a path, like these examples: + +- `m/84'/0'/0/*` +- `m/84'/0'/0'/*'` +- `m/9984/*` + +The star allows any number in the final position (only). It does not allow deeper paths. + +## Sharing Xpubs + +The Coldcard can calculate XPUB values for derived paths, if desired. +You can limit this feature by giving a list of permitted paths, or +the keyword `any` to allow any subpath. The master xpub (`m`) +is always available over USB protocol and cannot be disabled. + +## Share Derived Addresses + +Similarly, the Coldcard can calculate wallet addresses, if this +setting contains a list of whitelisted derivation paths. Star +patterns, and the keyword `any` can be used, as well as the keyword +`p2sh` which allows addresses in multisig wallets to be shared. + +In the case of multisig wallets, we do not check the script provided, +beyond the normal checks for inclusion into a known multisig wallet. + +# Other Policy + +This section covers global policy choices. Most settings are simple booleans. + +![other policy](img/snap-other-policy.png) + + +## Logging to MicroSD Card + +Two setting affect logging: _Must log_ and _Never log_. By default, +the Coldcard will log if a card is inserted. It does not fail if +the card is missing. If that is an issue for you, then set _Must log_ +and transactions will be refused if the card isn't installed and +working. _Never log_ is useful when you don't want to keep records +at the Coldcard's location. + +## Warnings Okay? + +This boolean allows the Coldcard to sign PSBT files that have +warnings. Typically warning are generated by overly-large fees or +weird path derivations. Since we don't expect warnings, any +transactions with a warning is normally refused. + +## Privacy over UX + +During development of the Bunker, we found there were numerous +status and informational values being shared over USB that, to some +degree, assist potential attackers. However, those values are needed +to provide a usable interface and a nice user experience (UX). + +If you set _Privacy over UX_, the following values will not be +shared over [USB in the HSM status response](protocol): + +- text summary of the spending policy +- count of approvals / refusals +- the number of time the storage locker has been read +- the period length +- when the period will end +- how much each rule has spent in current period +- system uptime +- list of usernames +- number of users which have provided auth credentials for current PSBT + +The CKBunker can operate in either mode, but you will find it harder +to use, as it's not possible to know where you stand in terms of +velocity spending and user authorization. + +## Boot to HSM + +This feature forces the Coldcard to start in HSM mode immediately +after boot up (after entry of the master PIN). + +You specify a 6-digit numeric code and if that code is provided in +the first 30 seconds after startup, the Coldcard will leave HSM +mode. (The HSM policy file is erased in this process.) Alternatively, +you may set _Do not accept any code_, and the Coldcard can never +leave HSM mode. + +!!! warning "Bricking Hazard" + + No changes to firmware, HSM policy, Coldcard settings will be possible—ever again. + + Not even the master PIN holder can change HSM policy nor escape HSM + mode! Firmware upgrades are not possible. + + +## Notes + +This is simply free-form text shown on the Coldcard when approving HSM Policy. +Up to 80 characters allowed. You could put the master password and/or +onion address here for documentation purposes. + + diff --git a/docs/setup.md b/docs/setup.md index d71f1eb..3c5c1f6 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -11,7 +11,7 @@ and "Bunker Setup" tabs. ## Coldcard Setup tab -![Coldcard Setup screen shot](cc-setup-tab.png) +![Coldcard Setup screen shot](img/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. @@ -27,7 +27,7 @@ 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) +Continue reading [here for details about HSM rules and policy.](policy.md) ### Using Coldcard Setup _without_ a Coldcard @@ -47,7 +47,7 @@ and start HSM mode on the command line. ## Bunker Setup tab -![Bunker Setup screen shot](bk-setup-tab.png) +![Bunker Setup screen shot](img/bk-setup-tab.png) There are only a few settings for the Bunker itself: @@ -61,11 +61,11 @@ There are only a few settings for the Bunker itself: - Simple Captcha - ![simple captcha](simple-captcha.png) + ![simple captcha](img/simple-captcha.png) - Animated Captcha - ![animated captcha](animated-captcha.gif) + ![animated captcha](img/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