Difference between revisions of "NitroKey HSM onboarding instructions"

From Internet Computer Wiki
Jump to: navigation, search
m
m
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
The NitroKey HSM onboarding path is the legacy onboarding path. If you wish to use the NitroKey HSM onboarding, follow steps 5-7 before returning to the [[Node Provider 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. 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==
 
==5. Install tools==
 
It's first necessary to install the necessary tools.
 
It's first necessary to install the necessary tools.

Latest revision as of 17:57, 28 May 2024

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.

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
    

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.

At this point, return to step 8 of the Node Provider Onboarding instructions