Nitrokey HSM 2 Integration Guide

This page covers the installation of required drivers and middleware, initialization of a Nitrokey HSM 2 device and its connection to MTG CARA via PKCS#11.

Supported Platforms

Operating System Supported Notes

Ubuntu 24.04 LTS

Yes

Full support. Official OpenSC packages available via apt.

RHEL 9+

Yes

Full support. Official OpenSC packages available via dnf.

openSUSE Leap 15.6

Yes

Full support. Official OpenSC packages available via zypper.

openSUSE Leap 16.0

Yes

Full support. OpenSC is pre-installed.

Install Required Packages

The following packages are required on the host that will have the Nitrokey HSM 2 physically connected to it:

  • opensc - provides pkcs11-tool, sc-hsm-tool, and the opensc-pkcs11.so PKCS#11 module

  • pcscd - PC/SC daemon, the middleware layer between the OS and the smartcard reader

  • libccid - CCID driver for USB smartcard readers, required for the HSM to be recognized

    Ubuntu 24.04
    sudo apt-get install -y opensc pcscd libccid
    RHEL 9+
    sudo dnf install -y opensc pcsc-lite pcsc-lite-ccid
    openSUSE 15.6 / 16.0
    sudo zypper install -y opensc pcsc-lite pcsc-lite-ccid
On openSUSE Leap 16.0, opensc is pre-installed. Verify pcsc-lite and pcsc-lite-ccid are present before proceeding.

Enable and start the PC/SC daemon:

sudo systemctl enable --now pcscd.service

Configure udev Rules

By default, USB smartcard devices are only accessible to root. The Nitrokey udev rules grant access to local users and service accounts without requiring elevated privileges.

Download and install the official Nitrokey udev rules:

sudo curl -fsSL \
  https://raw.githubusercontent.com/Nitrokey/nitrokey-udev-rules/main/41-nitrokey.rules \
  -o /etc/udev/rules.d/41-nitrokey.rules
sudo chown root:root /etc/udev/rules.d/41-nitrokey.rules
sudo chmod 644 /etc/udev/rules.d/41-nitrokey.rules

Reload the udev rules and trigger device re-evaluation:

sudo udevadm control --reload-rules && sudo udevadm trigger
The udev rules use the uaccess tag, which grants access to local users only. If your application runs as a system service connecting remotely (e.g. via SSH), you must additionally configure the udev rule with explicit MODE or OWNER settings.

Verify Device Detection

Plug in the Nitrokey HSM 2 and verify it is detected by the system:

pkcs11-tool --module opensc-pkcs11.so --list-slots

On a freshly connected, uninitialized device the output will look like this:

Available slots:
Slot 0 (0x0): Nitrokey Nitrokey HSM (010000000000000000000000) 00 00
  token label        :
  token manufacturer : www.CardContact.de
  token model        : PKCS#15 emulated
  token flags        : login required, rng, uninitialized, PIN pad present
  hardware version   : 24.13
  firmware version   : 3.4
  serial num         : 010000000000000000000000
  pin min/max        : 6/15

The uninitialized flag confirms the device has not yet been set up. If no slots are listed, consult the Troubleshooting section.

Initialise the HSM

Initialization configures the SO-PIN, user PIN, device label and, optionally, the Device Key Encryption Key (DKEK). This step is destructive: it erases all existing key material on the device. It must be performed before any keys can be generated or stored.

SO-PIN and User PIN

The SO-PIN must be exactly 16 hexadecimal characters (8 bytes). It cannot be alphanumeric. Using a non-hexadecimal or incorrectly sized SO-PIN will render the device permanently inaccessible.

Use a cryptographically random value. You can generate one with:

openssl rand -hex 8

Store both the SO-PIN and user PIN in a secure location (e.g. an offline password manager or physical safe). Loss of the SO-PIN is unrecoverable.

The user PIN must be between 6 and 15 characters.

DKEK (Device Key Encryption Key)

The DKEK is an optional, but strongly recommended mechanism, that enables encrypted export and import of key material between Nitrokey HSM 2 devices. Without a DKEK, private keys can never be exported from the device, making hardware failure an unrecoverable event.

The DKEK must be configured during initialisation and before any keys are generated. It cannot be added after the fact without re-initialising the device, which erases all key material.

For production deployments, Nitrokey recommends creating the DKEK share before initialization:

sc-hsm-tool --create-dkek-share dkek-share-1.pbe

You will be prompted to set a password for the share file. Store dkek-share-1.pbe and its password securely offline. This file is required to restore key material to a replacement device.

Run Initialisation

sc-hsm-tool --initialize \
  --so-pin <16-hex-char-SO-PIN> \   (1)
  --pin <user-PIN> \                (2)
  --label "MTG-CARA-HSM" \          (3)
  --dkek-shares 1                   (4)
1 Replace with your generated 16-character hexadecimal SO-PIN.
2 Replace with your chosen user PIN (6-15 characters).
3 A descriptive label for the token. Choose a name meaningful to your deployment.
4 Number of DKEK shares. Set to 0 to disable DKEK (not recommended for production).

If you configured a DKEK share, import it now before generating any keys:

sc-hsm-tool --import-dkek-share dkek-share-1.pbe

You will be prompted for the DKEK share password. On success the output will confirm:

DKEK share imported
DKEK shares    : 1
DKEK key check value : <hex value>

Note the DKEK key check value. Two devices with the same value share the same DKEK, which is required for key restoration to a replacement device.

Verify Initialisation

sc-hsm-tool

A successfully initialized device produces output similar to this:

Using reader with a card: Nitrokey Nitrokey HSM (010000000000000000000000) 00 00
Version              : 2.0
Config options       :
  User PIN reset with SO-PIN enabled
SO-PIN tries left    : 15
User PIN tries left  : 3
DKEK shares          : 1
DKEK key check value : 53CA37CEED5B227F

Confirm that:

  • SO-PIN tries left shows 15 (full, no failed attempts)

  • User PIN tries left shows 3

  • DKEK shares matches your configured value

  • The uninitialized flag is no longer present in pkcs11-tool --list-slots

PKCS#11 Module Path Reference

The path to the OpenSC PKCS#11 module differs by distribution and is required when configuring MTG CARA or running pkcs11-tool commands with an explicit module path.

Operating System PKCS#11 Module Path

Ubuntu 24.04

/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so

RHEL 9+

/usr/lib64/pkcs11/opensc-pkcs11.so

openSUSE 15.6 / 16.0

/usr/lib64/pkcs11/opensc-pkcs11.so

To verify the path on your system:

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

Backup and Restore Key Material

The Nitrokey HSM 2 backup mechanism uses the DKEK to wrap (encrypt) private key material into an encrypted binary file. The wrapped key can only be restored to a device that shares the same DKEK. Private key material never appears in plaintext outside the hardware boundary during this process.

Backup is only possible if the device was initialized with --dkek-shares 1 or more. A device initialized without DKEK support cannot export key material under any circumstances. There is no workaround: the device must be re-initialised, which erases all key material.

Determine Key References

Each key on the device has a numeric key reference required for wrap and unwrap operations. Key references are assigned by the application when keys are created and are not the same as the PKCS#11 key ID or label. Use pkcs15-tool to enumerate them:

pkcs15-tool --dump --pin <user-PIN>

Look for the Key ref field in each Private Key entry. Example output:

Private RSA Key [cara-rsa-ca]
    Object Flags   : [0x3], private, modifiable
    Usage          : [0x2E], decrypt, sign, signRecover, unwrap
    Access Flags   : [0x1D], sensitive, alwaysSensitive, neverExtract, local
    ModLength      : 4096
    Key ref        : 1 (0x1)     <-- this is the value needed for --key-reference
    Native         : yes
    ID             : 01

Private EC Key [cara-ec-ca]
    Object Flags   : [0x3], private, modifiable
    Usage          : [0x4], sign
    Access Flags   : [0x1D], sensitive, alwaysSensitive, neverExtract, local
    FieldLength    : 256
    Key ref        : 2 (0x2)     <-- this is the value needed for --key-reference
    Native         : yes
    ID             : 02

Note the Key ref value for each key before proceeding. You will need one backup file per key.

Backup

Wrap each key individually. The resulting .bin file contains the private key material encrypted with the DKEK, along with the key description and any associated certificate.

sc-hsm-tool --wrap-key <key-label>.bin \
  --key-reference <key-ref> \   (1)
  --pin <user-PIN>
1 The numeric Key ref value from pkcs15-tool --dump, not the label or PKCS#11 ID.

Repeat for each key on the device. Store the resulting .bin files alongside the DKEK share file (dkek-share-1.pbe) and its password. All three are required for a successful restore.

The wrapped key files are encrypted but still contain sensitive key material. Store them in a secure, access-controlled location, offline storage or an encrypted vault. Do not store them on the same host as the Nitrokey HSM 2.

Restore to a Replacement Device

The following procedure applies when replacing a failed or lost Nitrokey HSM 2 with a new one. The replacement device must be initialized with the same DKEK before keys can be imported.

Step 1 - Initialise the replacement device

Initialize the new device using the same number of DKEK shares as the original:

sc-hsm-tool --initialize \
  --so-pin <SO-PIN> \
  --pin <user-PIN> \
  --label "MTG-CARA-HSM" \
  --dkek-shares 1
The SO-PIN and user PIN do not need to match the original device. They are independent per device. Choose new values and record them securely.

Step 2 - Import the DKEK share

Import the same DKEK share file that was used during the original device initialisation. This is the critical step that allows the wrapped keys to be decrypted on the new device:

sc-hsm-tool --import-dkek-share dkek-share-1.pbe

You will be prompted for the DKEK share password. Verify the resulting DKEK key check value matches the original device before proceeding.

Step 3 - Unwrap keys

Import each wrapped key file onto the new device. Assign a key reference for each key: it does not need to match the original reference, but it must be unique on the device:

sc-hsm-tool --unwrap-key <key-label>.bin \
  --key-reference <key-ref> \   (1)
  --pin <user-PIN> \
  --force                        (2)
1 The key reference to assign on the new device. Use the same value as the original for consistency, or a new value if that reference is already occupied.
2 --force is required if the target key reference slot already contains a key or certificate.

Repeat for each wrapped key file. Verify the restored keys are visible:

pkcs15-tool --dump --pin <user-PIN>

The restored keys should appear with their original labels and descriptions.

Step 4 - Reconnect MTG CARA

With the replacement device initialized and keys restored, reconnect the device to the host and restart MTG CARA. No application-level reconfiguration is required, provided the device label and PKCS#11 slot configuration match the original.

Connect MTG CARA via PKCS#11

Configure the Application Properties

Before MTG CARA can use the Nitrokey HSM 2, it must be pointed at the OpenSC PKCS#11 module. Set the following property in /etc/opt/mtg-cara-ws-server/application.properties:

  • Ubuntu 24.04

  • RHEL 9+ / openSUSE 15.6 / 16.0

#######################################
# PKCS#11
#######################################
pkcs11Folder=/usr/lib/x86_64-linux-gnu/pkcs11/   (1)
#######################################
# PKCS#11
#######################################
pkcs11Folder=/usr/lib64/pkcs11/   (1)
1 This path must point to the directory containing opensc-pkcs11.so. Refer to thePKCS#11 Module Path Reference table if you are unsure of the correct path for your distribution.

Restart MTG CARA for the property change to take effect:

sudo systemctl restart mtg-cara-ws-server.service

Register the HSM Device in the CARA Admin UI

In the CARA Admin UI, navigate to Generic HSM → Devices and click Device hinzufügen (Add Device).

Configure the device with the following settings:

Field Value

HSM-Type

PKCS11

Device-Name

A descriptive name for the device, e.g. Nitrokey HSM 2

Cryptoki

opensc-pkcs11.so

Originaldatei der Cryptoki-Bibliothek verwenden

Enable this checkbox to use the library directly from the path configured in application.properties. No copy of the library will be created.

Domäne/Entity/Partition/Slot

0

HSM-Pool Konfiguration

Leave at the default values unless advised otherwise by MTG support.

Click Hinzufügen (Add) to save the device.

Connect and Log In

In the HSM device overview, click Details on the newly added device, then click Verbinden (Connect), to establish the connection to the HSM.

Once connected, click Anmelden (Log In) and enter the user PIN configured during HSM initialisation.

The HSM is now connected and the crypto user is authenticated. MTG CARA can create and use cryptographic material on the device.

Troubleshooting

No slots listed by pkcs11-tool

If pkcs11-tool --list-slots returns no output or an error, work through the following checks in order:

  1. Verify pcscd is running:

    systemctl status pcscd.service

    If it is not running, start it with sudo systemctl start pcscd.service.

  2. Verify the device is visible to the OS:

    lsusb | grep -i nitrokey

    The Nitrokey HSM 2 should appear as vendor ID 20a0, product ID 4230. If it is not listed, try a different USB port or cable.

  3. Verify the udev rules are applied:

    getfacl /dev/bus/usb/<bus>/<device>

    Replace <bus> and <device> with the values from the lsusb output. The ACL should include a user:<your-user>:rw- entry. If not, re-run the udev reload commands from Configure udev Rules.

ERROR: PKCS#11 module not found

If pkcs11-tool reports that it cannot find opensc-pkcs11.so, provide the full path explicitly using --module. Refer to the PKCS#11 Module Path Reference table for the correct path for your distribution.

SO-PIN or user PIN locked

The user PIN locks after 3 failed attempts. It can be reset using the SO-PIN:

pkcs11-tool --module opensc-pkcs11.so \
  --login --login-type so \
  --so-pin <SO-PIN> \
  --init-pin --new-pin <new-user-PIN>
The SO-PIN itself cannot be reset if lost. The device must be re-initialized, which will permanently erase all key material. There is no recovery path.

pcscd fails to start on RHEL 9

On some minimal RHEL 9 installations the ccid driver is not loaded automatically. Verify it is present:

rpm -q pcsc-lite-ccid

If not installed, add it with sudo dnf install -y pcsc-lite-ccid and restart pcscd.