§ Wiki · Wiki entry

NitroKey HSM Installation Runbook

Legacy runbook for initializing a NitroKey HSM with the OpenSC tooling, generating the EC keypair, and deriving the node operator principal — only required for Gen-1 onboarding.

·May 4, 2026·4 min read

[!WARNING] The NitroKey HSM onboarding path is the legacy flow. Node providers operating Gen-2 hardware must onboard without an HSM — see Node Provider Onboarding and the Node Deployment Guide (Gen-2). This runbook only applies to Gen-1 onboarding flows that explicitly use a NitroKey HSM.

This runbook covers the HSM-side setup that precedes Gen-1 node deployment: installing the OpenSC tooling, initializing the NitroKey, generating an EC keypair, and recovering the node operator principal. On completion, return to step 8 of Node Provider Onboarding.

The numbering below begins at step 5 to match the position of these operations within the broader onboarding flow.

5. Install tools

You need the OpenSC PKCS#11 tooling installed locally before initializing the HSM.

macOS

  1. Download the OpenSC installer: OpenSC-0.22.0.dmg.
  2. Open the DMG, then double-click the OpenSC PKG file inside.
  3. If macOS blocks the installer because it is from an unidentified developer:
    • Open the Apple menu → System Preferences → Security and Privacy.
    • Click the lock icon and authenticate.
    • On the General tab, click Open anyway next to the OpenSC entry.
  4. Continue through the installer until it completes.

[!NOTE] On macOS Sonoma, OpenSC may fail to read the HSM with this error:

Error while trying to read the public key from the HSM. Underlying error: Utility command failed with status exit status: 1: Error while running '`pkcs11-tool --read-object --slot 0 --type pubkey --id 01` input: ': error: PKCS11 function C_OpenSession failed: rv = CKR_DEVICE_ERROR (0x30)

The fix is to install the bundled CCID driver into the local SmartCardServices path and reboot:

sudo mkdir -p /usr/local/libexec/SmartCardServices/drivers
sudo cp -a /usr/libexec/SmartCardServices/drivers/ifd-ccid.bundle /usr/local/libexec/SmartCardServices/drivers
sudo reboot

Source: OpenSC issue #2887.

Linux

The instructions below have been verified on Ubuntu 20.04. Install pcscd and opensc:

sudo add-apt-repository universe
sudo apt update
sudo apt install pcscd opensc

6. Set up the node operator keys

With the HSM plugged in, initialize it, change the SO-PIN, and create the EC keypair the network will identify the node operator by.

Initialize the HSM

sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 358138

Change the SO-PIN

[!WARNING] The new SO-PIN must be 16 hexadecimal digits. This is poorly documented elsewhere and some operators have permanently lost access to a NitroKey HSM by entering ordinary characters — the tool will accept the bad PIN without warning.

[!WARNING] Do not change the user PIN. It must remain at the default (358138) for the onboarding scripts to function.

pkcs11-tool --login --login-type so --so-pin 3537363231383830 --change-pin

Create the keypair

Enter the default user PIN (358138) when prompted.

pkcs11-tool -k --key-type EC:prime256v1 --login -d 01

[!TIP] Key backup may be possible — see the SmartCard-HSM key backup and restore notes.

7. Get the node operator principal

Configure the dfx identity

Skip this step if you already configured a node-operator-hsm identity for another HSM.

[!NOTE] The path to opensc-pkcs11.so varies by platform and OpenSC version. To locate it:

find / -name opensc-pkcs11.so 2> /dev/null

macOS:

dfx identity new node-operator-hsm \
  --hsm-key-id 01 \
  --hsm-pkcs11-lib-path /Library/OpenSC/lib/opensc-pkcs11.so

Linux:

dfx identity new node-operator-hsm \
  --hsm-key-id 01 \
  --hsm-pkcs11-lib-path /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so

Recover the principal

NODE_OPERATOR_PRINCIPAL=$(DFX_HSM_PIN=358138 dfx --identity node-operator-hsm identity get-principal)
echo $NODE_OPERATOR_PRINCIPAL

Expected form:

uqquy-76uhn-2mys5-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx

[!WARNING] Retain physical access to the HSM for the rest of the onboarding flow. You will need it again at Node Provider Roadmap milestone five, when the node machines themselves are onboarded.

What to do next

Return to step 8 of Node Provider Onboarding to register the node provider principal with the network. When you later install IC-OS on the actual hardware, follow the Node Deployment Guide (Gen-1, with HSM).

Related