HSM Mode Features

USB Protocol for HSM Mode

New Commands

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:

Only specific USB commands are whitelisted for use once HSM mode has been activated:

All other USB commands will fail during HSM mode.

Unchanged Commands

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.

HSM Status Response

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'
            'Velocity Period:\n'
            ' 720 minutes\n'
            ' = 12 hrs\n'
            'Message signing:\n'
            "- Allowed if path matches: m/84/0'/0' OR m/3\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}
Understanding the Status Response

Here are the fields of the status response.

Not all will be present depending on policy and system state.