View source for 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 [[Node Provider Machine Hardware Guide|Gen 2 hardware]] must onboard '''without''' a NitroKey HSM. If you wish to onboard without a NitroKey HSM, return to the [[Node Provider Onboarding#6. Setup the Node Operator keys|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===
#Download this OpenSC binary: https://github.com/OpenSC/OpenSC/releases/download/0.22.0/OpenSC-0.22.0.dmg
#Double click the DMG image that you downloaded and then double click the OpenSC PKG file.
#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 &gt; System Preferences &gt; 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”.
#Click continue and install until the installation is complete.
===Linux===
NOTE: The instructions below have been tested with the Ubuntu 20.04 release.

Install pcscd and opensc:
:<syntaxhighlight lang="shell">
$ sudo add-apt-repository universe
$ sudo apt update
$ sudo apt install pcscd opensc
</syntaxhighlight>
==6. Setup the Node Operator keys==
#Initialize the HSM.<syntaxhighlight lang="shell">
$ sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 358138
</syntaxhighlight>
#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'''<syntaxhighlight lang="shell">
$ pkcs11-tool --login --login-type so --so-pin 3537363231383830 --change-pin
</syntaxhighlight>
#Create a keypair on the HSM. Enter the default pin 358138 when prompted.<syntaxhighlight lang="shell">
$ pkcs11-tool -k --key-type EC:prime256v1 --login -d 01
</syntaxhighlight>
#*'''Note:''' Key backup may be possible with [https://github.com/OpenSC/OpenSC/wiki/SmartCardHSM#using-key-backup-and-restore these instructions].
==7. Get the node operator principal==
#Configure dfx identity (skip this step if you already configured it for another HSM).
#*'''Note:''' Depending on your installation, the path to the <code>--hsm-pkcs11-lib-path</code> might be different on your platform. You can locate the correct path with the following command:<syntaxhighlight lang="shell">
$ find / -name opensc-pkcs11.so 2> /dev/null
</syntaxhighlight>
#*MacOS<syntaxhighlight lang="shell">
$ dfx identity new node-operator-hsm --hsm-key-id 01 --hsm-pkcs11-lib-path /Library/OpenSC/lib/opensc-pkcs11.so
</syntaxhighlight>
#*Linux<syntaxhighlight lang="shell">
$ dfx identity new node-operator-hsm --hsm-key-id 01 --hsm-pkcs11-lib-path /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so
</syntaxhighlight>
#Get the principal.<syntaxhighlight lang="shell">
$ 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
</syntaxhighlight>

Note: you must retain access to the HSM for when you onboard nodes in [[Node Provider Roadmap#Milestone%20Five:%20Node%20Machine%20Onboarding|roadmap milestone five.]]

=== '''At this point, return to step 8 of the [[Node Provider Onboarding#8. Register your Node Provider principal to the network|Node Provider Onboarding]] instructions''' ===