NitroKey HSM onboarding instructions

The NitroKey HSM onboarding path is the legacy onboarding path. Onboarding without a NitroKey HSM is the recommended onboarding path. In particular, node providers onboarding Gen 2 hardware must onboard without a NitroKey HSM. To onboard without a NitroKey HSM, return to the Node Provider Onboarding.

If you wish to use the NitroKey HSM onboarding, follow steps 5-7 before returning to the Node Provider Onboarding instructions.

5. Install tools

It's first necessary to install the necessary tools.

MacOS

1. Download this OpenSC binary: https://github.com/OpenSC/OpenSC/releases/download/0.22.0/OpenSC-0.22.0.dmg
2. Double click the DMG image that you downloaded and then double click the OpenSC PKG file.
3. If your system doesn't allow the installation software from an unidentified developer please follow these steps or contact your system administrator:
   • Choose the Apple menu > System Preferences > click Security and Privacy.
   • Click the lock Icon to unlock it, then enter an administrator name and password.
   • Ensure that you're on the tab named “General”.
   • You should see the OpenSC app and you should be able to enable its installation by choosing “Open anyway”.
4. Click continue and install until the installation is complete.

   NOTE: If you’re getting a CKR_DEVICE_ERROR when using your NitroKey and are using macOS Sonoma:

   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)

   Run the following (this will restart your machine) and your nitrokey should start working again:

   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: https://github.com/OpenSC/OpenSC/issues/2887#issuecomment-1810783804

Linux

NOTE: The instructions below have been tested with the Ubuntu 20.04 release.

Install pcscd and opensc:

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

6. Setup the Node Operator keys

1. Initialize the HSM.

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

2. Change the HSM so-pin.
   • WARNING: The new HSM so pin must have 16 hexadecimal digits. This is not very well known, and some HSM users have lost access to a Nitrokey HSM because they tried using regular characters and the command below accepted it.
   • Do NOT change the user pin. It must remain as the default for the onboarding scripts to work

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

3. Create a keypair on the HSM. Enter the default pin 358138 when prompted.

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

   • Note: Key backup may be possible with these instructions.

7. Get the node operator principal

1. Configure dfx identity (skip this step if you already configured it for another HSM).
   • Note: Depending on your installation, the path to the --hsm-pkcs11-lib-path might be different on your platform. You can locate the correct path with the following command:

     $ 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
     

2. Get the principal.

   $ NODE_OPERATOR_PRINCIPAL=$(DFX_HSM_PIN=358138 dfx --identity node-operator-hsm identity get-principal)
   $ echo $NODE_OPERATOR_PRINCIPAL
   
   uqquy-76uhn-2mys5-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
   

Note: you must retain access to the HSM for when you onboard nodes in roadmap milestone five.