There are some new commands added to support HSM mode. Check out the latest
version (1.0 or higher) of ckcc-protocol
for the details and command-line example
code. In summary, new commands include:
hsms
- HSM Start (after uploading JSON policy file)hsts
- Return HSM Status (gives JSON values, see below)nmur
- Create a new userrmur
- Delete a useruser
- Provide authorization details for a usergslr
- Read contents of Storage LockerOnly specific USB commands are whitelisted for use once HSM mode has been activated:
logo
, ping
, vers
: harmless/boringupld
, sha2
, dwld
, stxn
: upload/download/sign PSBT needed; firmware blockedmitm
, ncry
: USB encryption setupsmsg
: limited by policy msg_paths
blkc
, hsts
: report status valuesstok
, smok
: completion check: sign txn or msgxpub
: limited by policy allow_xpub
but m
always allowedmsck
: multisig wallet quick checkp2sh
, show
: limited by HSM policy: allow_addrs
user
: auth HSM user, other user cmds not allowedgslr
: read storage locker; hsm mode only, limited usageAll other USB commands will fail during HSM mode.
The key commands for uploading and signing a PSBT file are not changed. This means you could use Electrum with a Coldcard in HSM mode.
You can query the state of the HSM features in the Coldcard at any time, and should expect a simple JSON document as the response.
When the HSM is not enabled, you will get a short response like this:
% ckcc hsm
{'active': False,
'chain': 'XTN',
'policy_available': False,
'users': [],
'wallets': []}
Once enabled, the result depends heavily on the priv_over_ux
setting,
and the many other values in your HSM policy.
% ckcc hsm
{'active': True,
'approvals': 0,
'chain': 'XTN',
'last_refusal': None,
'pending_auth': 0,
'period': 720,
'refusals': 0,
'sl_reads': 0,
'summary': 'Transactions:\n'
'- Rule #1: Up to 0.00001 XTN per txn will be approved\n'
'\n'
'Velocity Period:\n'
' 720 minutes\n'
' = 12 hrs\n'
'\n'
'Message signing:\n'
"- Allowed if path matches: m/84/0'/0' OR m/3\n"
'\n'
'Other policy:\n'
'- MicroSD card will receive log entries.\n'
'- Storage Locker will be updated, and can be read 2 times.\n'
'- XPUB values will be shared, if path matches: m OR m/3.\n',
'uptime': 3284,
'users': ['alice', 'bob', 'baz']}
With priv_over_ux
enabled, the status response is minimal:
% ckcc hsm
{'active': True,
'approvals': 0,
'chain': 'XTN',
'last_refusal': None,
'refusals': 0}
Here are the fields of the status response.
active
: is the HSM mode activated?chain
: either BTC or XTN (testnet)last_refusal
: short text explanation of why the last request failedapprovals
, refusals
: counts of number of PSBT or msg signings doneperiod
: number of minutes in the period (from policy file)uptime
: number of seconds the Coldcard has been runningusers
: list of defined Coldcard usersnext_local_code
: if defined, one or more rules needs local confirmation, and this
value is a factor in the PIN calculation. 15 bytes encoded in Base64.summary
: text of the policy as shown to user during confirmation stepsl_reads
: number of reads of the storage lockerperiod_ends
: number of seconds until the current period endshas_spent
: a list of amount spent in this period, by each rule (in order by rule)pending_auth
: count of auth details already submitted before PSBT receivedNot all will be present depending on policy and system state.
We've found relevant search results.