---
title: NitroKey HSM Installation Runbook
slug: nitrokey-hsm-installation
description: 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.
tags:
  - node-provider
  - hsm
  - nitrokey
  - runbook
  - gen-1
date: 2026-05-04
related:
  - node-provider-documentation
  - node-deployment-gen-1
  - node-provider-onboarding
  - node-hardware-guide
---

> [!WARNING]
> The NitroKey HSM onboarding path is the **legacy** flow. Node
> providers operating [Gen-2 hardware](/wiki/node-hardware-guide/)
> must onboard **without** an HSM — see
> [Node Provider Onboarding](/wiki/node-provider-onboarding/) and the
> [Node Deployment Guide (Gen-2)](/wiki/node-deployment-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](/wiki/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`](https://github.com/OpenSC/OpenSC/releases/download/0.22.0/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:
>
> ```shell
> 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](https://github.com/OpenSC/OpenSC/issues/2887#issuecomment-1810783804).

### Linux

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

```shell
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

```shell
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.

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

### Create the keypair

Enter the default user PIN (`358138`) when prompted.

```shell
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](https://github.com/OpenSC/OpenSC/wiki/SmartCardHSM#using-key-backup-and-restore).

## 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:
>
> ```shell
> find / -name opensc-pkcs11.so 2> /dev/null
> ```

**macOS:**

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

**Linux:**

```shell
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

```shell
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](/wiki/node-provider-roadmap/),
> when the node machines themselves are onboarded.

## What to do next

Return to step 8 of [Node Provider Onboarding](/wiki/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)](/wiki/node-deployment-gen-1/).

## Related

- [Node Provider Onboarding](/wiki/node-provider-onboarding/) — the
  surrounding onboarding flow this runbook plugs into.
- [Node Deployment Guide (Gen-1, with HSM)](/wiki/node-deployment-gen-1/)
  — the deployment runbook that consumes the prepared HSM.
- [Node Provider Documentation](/wiki/node-provider-documentation/) —
  the parent index for the role.
- [Node Provider Machine Hardware Guide](/wiki/node-hardware-guide/) —
  hardware specifications by generation.