Nitropy Opdrachtregel Programma#

Deze tutorial demonstreert hoe je toegang krijgt tot het NetHMS via nitropy command line tool, die je moet downloaden en installeren.

Notitie

Als u een NetHSM-demo-instantie met een zelfondertekend certificaat gebruikt, bijvoorbeeld met het Docker-image, moet u de optie --no-verify-tls gebruiken voor nitropy om de certificaatcontrole over te slaan.

Notitie

Stel eerst de waarde van $NETHSM_HOST in op het IP-adres of de URL van je NetHSM. Onze demo server kan worden bereikt op https://nethsmdemo.nitrokey.com/

Apparaatinformatie & Status#

$ nitropy nethsm --host $NETHSM_HOST info

Host:    localhost:8443
Vendor:  Nitrokey GmbH
Product: NetHSM
$ nitropy nethsm --host $NETHSM_HOST state

NetHSM localhost:8443 is Unprovisioned

Provisioning#

Een nieuwe NetHSM moet eerst voorzien worden van passphrases en de huidige tijd. De Admin Passphrase is de passphrase van de Administrator, die de supergebruiker van de NetHSM is. De Unlock Passphrase wordt gebruikt om de vertrouwelijke gegevensopslag van de NetHSM te versleutelen.

Notitie

De NetHSM demo instance op nethsmdemo.nitrokey.com is al voorzien.

$ nitropy nethsm --host $NETHSM_HOST provision

NetHSM localhost:8443 provisioned

NetHSM kan worden gebruikt in Attended Boot-modus en Unattended Boot-modus.

  • In de modus Attended Boot moet bij elke start de Unlock Passphrase worden ingevoerd, die wordt gebruikt om de opgeslagen gegevens te versleutelen. Om veiligheidsredenen wordt deze modus aanbevolen.

  • In de modus Unattended Boot is geen ontgrendelingspassphrase vereist, daarom kan de NetHSM zonder toezicht starten en wordt de gegevensopslag onversleuteld opgeslagen. Gebruik deze modus als niet aan uw beschikbaarheidseisen kan worden voldaan met de modus Attended Boot.

De huidige modus opvragen:

$ nitropy nethsm --host $NETHSM_HOST get-config --unattended-boot

 Configuration for NetHSM localhost:8443:
 Unattended boot: off

Zet de Unattended Boot modus aan:

$ nitropy nethsm --host $NETHSM_HOST set-unattended-boot on

 Updated the unattended boot configuration for NetHSM localhost:8443

Gebruikersbeheer#

Rollen#

Scheiding van taken kan worden geïmplementeerd door gebruik te maken van de beschikbare Rollen. Aan elke gebruikersaccount die op de NetHSM is geconfigureerd, is een van de volgende Rollen toegewezen. Hieronder volgt een beschrijving op hoog niveau van de operaties die zijn toegestaan door individuele Rollen, voor eindpunt-specifieke details wordt verwezen naar de REST API documentatie.

  • R-Administrator: Een gebruikersaccount met deze rol heeft toegang tot alle operaties die door de REST API worden aangeboden, met uitzondering van de operaties voor het gebruik van sleutels, d.w.z. ondertekening en ontcijfering van berichten.

  • R-Operator: Een gebruikersaccount met deze rol heeft toegang tot alle sleutelgebruikoperaties, een alleen-lezen subset van sleutelbeheeroperaties en gebruikersbeheeroperaties die alleen wijzigingen voor hun eigen account toestaan.

  • R-Metrics: Een gebruikersaccount met deze rol heeft alleen toegang tot read-only metrics operaties.

  • R-Backup: Een gebruikersaccount met deze rol heeft alleen toegang tot de handelingen die nodig zijn om een systeembackup te starten.

Opmerking: In toekomstige versies kunnen extra rollen worden geïntroduceerd.

Aanmaken & verwijderen van gebruikers

Maak nu een nieuwe gebruiker aan met de operator rol die gebruikt kan worden om gegevens te ondertekenen en te ontsleutelen. Merk op dat de NetHSM een willekeurige gebruikers-ID toekent als we die niet specificeren.

$ nitropy nethsm --host $NETHSM_HOST  add-user --real-name "Jane User" --role Operator

User Operator added to NetHSM localhost:8443
$ nitropy nethsm --host $NETHSM_HOST delete-user "Jane User"

Sleutelbeheer#

Genereer sleutels#

In deze handleiding willen we een RSA sleutel gebruiken om gegevens te decoderen met PKCS #1 en om gegevens te ondertekenen met PSS met SHA256. Laten we dus een nieuwe sleutel op de NetHSM genereren. Zorg ervoor dat u het RSA algoritme gebruikt en dat u het RSA_Signature_PSS_SHA256 en RSA_Decryption_PKCS1 sleutelmechanismen selecteert. Als u geen sleutel-ID opgeeft, genereert de NetHSM een willekeurige ID voor de nieuwe sleutel.

$ nitropy nethsm --host $NETHSM_HOST  generate-key --type RSA --mechanism RSA_Signature_PSS_SHA256 --mechanism RSA_Decryption_PKCS1 --length 2048 --key-id myFirstKey

Key myFirstKey generated on NetHSM localhost:8443

Sleutels importeren#

In plaats van een sleutel op de NetHSM te genereren, kunt u ook bestaande privé-sleutels in de NetHSM importeren:

$ nitropy nethsm --host $NETHSM_HOST  add-key --type RSA --mechanism RSA_Signature_PSS_SHA256 --mechanism RSA_Decryption_PKCS1 --key-id mySecondKey --public-exponent AQAB --prime-p "AOnWFZ+JrI/xOXJU04uYCZOiPVUWd6CSbVseEYrYQYxc7dVroePshz29tc+VEOUP5T0O8lXMEkjFAwjW6C9QTAsPyl6jwyOQluMRIkdN4/7BAg3HAMuGd7VmkGyYrnZWW54sLWp1JD6XJG33kF+9OSar9ETPoVyBgK5punfiUFEL" \
    --prime-q "ANT1kWDdP9hZoFKT49dwdM/S+3ZDnxQa7kZk9p+JKU5RaU9e8pS2GOJljHwkES1FH6CUGeIaUi81tRKe2XZhe/163sEyMcxkaaRbBbTc1v6ZDKILFKKt4eX7LAQfhL/iFlgi6pcyUM8QDrm1QeFgGz11ChM0JuQw1WwkX06lg8iv"

Key mySecondKey added to NetHSM localhost:8443

Lijst Sleutels#

Om er zeker van te zijn dat de sleutel is aangemaakt en de juiste algoritme- en mechanisme-instellingen heeft, kunnen we alle sleutels op de NetHSM opvragen:

$ nitropy nethsm --host $NETHSM_HOST list-keys
Keys on NetHSM localhost:8443:

Key ID          Algorithm       Mechanisms                                      Operations
----------      ---------       ----------------------------------------------  ----------
myFirstKey      RSA             RSA_Decryption_PKCS1, RSA_Signature_PSS_SHA256  0
mySecondKey     RSA             RSA_Decryption_PKCS1, RSA_Signature_PSS_SHA256  0

Toon sleutel details#

We kunnen ook de publieke sleutel van het gegenereerde sleutelpaar opvragen:

$ nitropy nethsm --host $NETHSM_HOST get-key myFirstKey

Om de sleutel met OpenSSL te kunnen gebruiken, exporteren we hem als een PEM-bestand en slaan we hem op als public.pem:

$ nitropy nethsm --host $NETHSM_HOST get-key myFirstKey --public-key > public.pem

We kunnen de sleutel inspecteren met openssl en hem gebruiken voor encryptie of handtekening verificatie (zoals beschreven in de volgende sectie):

$ openssl rsa -in public.pem -pubin -text

RSA Public-Key: (2048 bit)
Modulus:
          00:c3:56:f5:09:cc:a9:3e:ca:16:2e:fb:d2:8b:9d:
          a9:33:5a:87:8f:3f:7a:bb:8a:3d:62:9b:5d:56:84:
          95:97:bb:97:f0:77:e2:c8:59:f2:b5:c6:b7:f5:b3:
          76:69:a3:e8:f6:b7:35:f4:3c:52:6d:3c:a0:b6:a1:
          e4:1a:32:05:1d:51:68:21:7d:fc:53:69:ec:bc:0b:
          a0:db:63:b2:0e:47:00:03:4d:98:1f:ab:c0:7b:2e:
          3c:8f:b6:36:ff:f0:db:80:26:f0:a6:af:30:2f:7b:
          16:fd:5c:db:0f:2c:54:8a:26:2b:db:3d:78:49:4b:
          7b:d1:60:ea:a7:f0:b4:5e:fc:33:ff:57:f8:83:fd:
          12:64:8f:29:d1:94:96:9a:15:18:5d:04:ca:1c:29:
          44:ad:42:31:c5:80:38:4c:eb:3b:b8:7e:17:27:5c:
          69:a8:88:44:ea:d1:82:64:fe:51:31:47:97:a7:a9:
          87:c3:13:c9:00:7a:b9:fb:6f:cc:66:4c:07:d7:68:
          fa:78:68:9a:e7:87:1e:94:c6:27:92:5f:f2:7d:11:
          44:11:b5:39:35:59:2c:cd:f9:4f:59:e3:56:93:1f:
          94:20:fd:6b:23:0d:15:e6:4e:bb:84:a8:a5:0d:9f:
          1c:90:ab:a8:10:04:50:12:c1:80:02:94:85:78:df:
          d6:b3
Exponent: 65537 (0x10001)
writing RSA key
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw1b1CcypPsoWLvvSi52p
M1qHjz96u4o9YptdVoSVl7uX8HfiyFnytca39bN2aaPo9rc19DxSbTygtqHkGjIF
HVFoIX38U2nsvAug22OyDkcAA02YH6vAey48j7Y2//DbgCbwpq8wL3sW/VzbDyxU
iiYr2z14SUt70WDqp/C0Xvwz/1f4g/0SZI8p0ZSWmhUYXQTKHClErUIxxYA4TOs7
uH4XJ1xpqIhE6tGCZP5RMUeXp6mHwxPJAHq5+2/MZkwH12j6eGia54celMYnkl/y
fRFEEbU5NVkszflPWeNWkx+UIP1rIw0V5k67hKilDZ8ckKuoEARQEsGAApSFeN/W
swIDAQAB
-----END PUBLIC KEY-----

Sleutelcertificaten#

Het is mogelijk certificaten in te stellen en op te vragen voor de sleutels die op een NetHSM-instantie zijn opgeslagen:

$ nitropy nethsm --host $NETHSM_HOST  set-certificate myFirstKey --mime-type application/x-pem-file /tmp/cert.pem

Updated the certificate for key myFirstKey on NetHSM localhost:8443
$ nitropy nethsm --host $NETHSM_HOST get-certificate myFirstKey > /tmp/cert.pem

Verzoeken om ondertekening van sleutelcertificaten#

De NetHSM ondersteunt het genereren van Certificate Signing Requests (CSR) voor de opgeslagen sleutels:

$ nitropy nethsm --host $NETHSM_HOST csr --key-id myFirstKey --country DE --state-or-province BE --locality Berlin --organization ACME --organizational-unit IT --common-name example.com --email-address it@example.com

Belangrijkste operaties#

We kunnen gegevens versleutelen voor de sleutel die op de NetHSM is opgeslagen met OpenSSL. (public.pem is het bestand met de openbare sleutel dat we hebben aangemaakt in de sectie Details van de sleutel weergeven).

$ echo 'NetHSM rulez!' | OpenSSL rsautl -encrypt -inkey public.pem -pubin | base64 > data.crypt
$ nitropy nethsm -h $NETHSM_HOST decrypt -k myFirstKey -d "$(cat data.crypt)" -m PKCS1 | base64 -d

NetHSM rulez!

Op dezelfde manier kunnen wij gegevens ondertekenen met de sleutel op de NetHSM. Voor RSA en ECDSA moeten we eerst een digest berekenen:

$ echo 'NetHSM rulez!' > data
$ openssl dgst -sha256 -binary data | base64 > data.digest

Dan kunnen we van deze digest een handtekening maken met de NetHSM:

$ nitropy nethsm -h $NETHSM_HOST sign -k myFirstKey -m PSS_SHA256 -d "$(cat data.digest)" | base64 -d > data.sig

En gebruik dan OpenSSL om de handtekening te verifiëren:

$ openssl dgst -sha256 -verify public.pem -signature data.sig -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:-1 data

Verified OK

Back-ups maken#

Het is mogelijk om een backup van de NetHSM te maken die zowel de configuratie als de opgeslagen sleutels vastlegt. Om een backup te maken, moet eerst een backup-wachtzin worden ingesteld die wordt gebruikt om het backup-bestand te versleutelen:

$ nitropy nethsm -h $NETHSM_HOST -u admin set-backup-passphrase

Updated the backup passphrase for NetHSM localhost:8443

Nu moet je een gebruiker aanmaken met de R-Backup rol:

$ nitropy nethsm -h $NETHSM_HOST -u admin add-user --user-id backup --real-name "Backup User" --role backup

User backup added to NetHSM localhost:8443

Dan kunt u de backup genereren en wegschrijven naar een bestand:

$ nitropy nethsm -h $NETHSM_HOST backup /tmp/nethsm-backup

Backup for localhost:8443 written to /tmp/backup

Back-ups terugzetten#

Dit backupbestand kan worden teruggezet op een niet-geprovisioneerde NetHSM-instantie:

$ nitropy nethsm -h $NETHSM_HOST restore --backup-passphrase backup-passphrase backupencryptionkey /tmp/nethsm-backup

Backup restored on NetHSM localhost:8443

Bijwerken van NetHSM#

Waarschuwing

Er kan gegevensverlies optreden als gevolg van de installatie van een beta-update!

$ nitropy nethsm --host $NETHSM_HOST  update /tmp/nethsm-update.img.cpio

Image /tmp/nethsm-update.img.cpio uploaded to NetHSM localhost:8443

Als u verder wilt gaan met de installatie, kunt u de update nu vastleggen:

$ nitropy nethsm --host $NETHSM_HOST     commit-update

Update successfully committed on NetHSM localhost:8443

U kunt de update ook annuleren:

$ nitropy nethsm --host $NETHSM_HOST  cancel-update

Update successfully cancelled on NetHSM localhost:8443