CLI Commands for HSM
The ckcc helper program, or any other program which can speak
Coldcard's USB protocol, and be used in HSM mode. Once HSM mode is
started, the usual signing commands are used, but without the need
for user interaction. There are a few commands that are disabled
in HSM mode, but those are not involved in PSBT or message signing.
To authorize PSBT signing, you may need to use the "auth" command, which transmits a OTP (6 digit) code, or hashed password to the Coldcard.
If the local operator must confirm, then you will need to calculate the
appropriate code to be entered. Use ckcc local-conf for this.
Fetch the status of the HSM using ckcc hsm.
Uploading a Policy#
To upload a policy file and prompt the local user to start HSM mode, use
ckcc hsm-start:
% ckcc hsm-start policy.json
Approve HSM policy on Coldcard screen.
# Validate the JSON without uploading:
% ckcc hsm-start policy.json --dry-run
Policy ok
# Re-start with the policy already saved on the device:
% ckcc hsm-start
Approve HSM policy on Coldcard screen.
The HSM-related USB commands (hsm-start, hsm, user, local-conf,
auth, etc.) require the HSM Mode toggle to be enabled on the device
first — see HSM Mode and CKBunker.
Example Sequence#
Starting with the policy file (JSON), shown
as an example on this page,
and with the Coldcard already in HSM mode, you might sign a transaction with this
sequence of ckcc commands:
% ckcc hsm
{'active': True,
'approvals': 0,
'chain': 'XTN',
'last_refusal': None,
'next_local_code': 'BrstN9qZ28pEaBdrUs3K',
'pending_auth': 0,
'period': 240,
'refusals': 0,
'sl_reads': 1,
'summary': '=-=\n'
...
"m/84'/0'/0'/*.\n",
'uptime': 491.477,
'users': ['alice', 'bob']}
% ckcc auth alice 111111
Correct or queued
% ckcc sign test.psbt --visualize
232 bytes (start @ 0) to send from 'attempt.psbt'
Ok! Downloading result (95 bytes)
0.99990000 XTN
- to address -
mzwtncBV2T5ikNmPf1u6TuEQYys6RPsLxp
Network fee:
0.00010000 XTN
% ckcc x sign test.psbt -6
232 bytes (start @ 0) to send from 'attempt.psbt'
Waiting for OK on the Coldcard...
You refused permission to do the operation
% ckcc hsm | grep last_refusal
'last_refusal': "User 'alice' gave wrong auth value: mismatch",
% ckcc hsm | grep pending_auth
'pending_auth': 0,
% ckcc sign test.psbt -6
232 bytes (start @ 0) to send from 'attempt.psbt'
Waiting for OK on the Coldcard...
You refused permission to do the operation
% ckcc hsm
...
'last_refusal': "Rejected: rule #1: local operator didn't confirm, rule #2: "
'need user(s) confirmation, rule #3: non-whitelisted address: '
'mzwtncBV2T5ikNmPf1u6TuEQYys6RPsLxp',
...
% ckcc local-conf test.psbt
Local authorization code is:
891443