Nitropy Kommandozeilenprogramm#

Geräteinformationen & Status
Bereitstellung
Benutzerverwaltung
- Rollen
Schlüsselverwaltung
Schlüssel-Zertifikate
- Signieranforderungen für Schlüsselzertifikate
Wichtige Vorgänge
Erstellen von Backups
Wiederherstellung von Backups
NetHSM aktualisieren

In diesem Tutorial wird gezeigt, wie man über das nitropy-Kommandozeilen-Tool, das Sie herunterladen und installieren müssen, auf das NetHMS zugreift.

Bemerkung

Wenn Sie eine NetHSM-Demo-Instanz mit einem selbstsignierten Zertifikat verwenden, zum Beispiel mit dem Docker-Image, müssen Sie die Option --no-verify-tls für nitropy verwenden, um die Zertifikatsprüfung zu überspringen.

Bemerkung

Setzen Sie zunächst den Wert von $NETHSM_HOST auf die IP-Adresse oder URL Ihres NetHSM. Unser Demoserver ist unter https://nethsmdemo.nitrokey.com/ zu erreichen.

Geräteinformationen & 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

Bereitstellung #

Ein neuer NetHSM muss zunächst mit Passphrasen und der aktuellen Uhrzeit eingerichtet werden. Die Admin-Passphrase ist die Passphrase des Administrators, der der Superuser des NetHSM ist. Die Unlock Passphrase wird verwendet, um den vertraulichen Datenspeicher des NetHSM zu verschlüsseln.

Bemerkung

Die NetHSM-Demo-Instanz unter nethsmdemo.nitrokey.com ist bereits eingerichtet.

$ nitropy nethsm --host $NETHSM_HOST provision

NetHSM localhost:8443 provisioned

NetHSM kann im Attended Boot-Modus und im Unattended Boot-Modus verwendet werden.

Im Modus Attended Boot muss bei jedem Start die Unlock Passphrase eingegeben werden, die zur Verschlüsselung des Datenspeichers verwendet wird. Aus Sicherheitsgründen wird dieser Modus empfohlen.
Im Modus Unattended Boot ist keine Unlock Passphrase erforderlich, daher kann der NetHSM unbeaufsichtigt starten und der Datenspeicher wird unverschlüsselt gespeichert. Verwenden Sie diesen Modus, wenn Ihre Verfügbarkeitsanforderungen mit dem Attended Boot-Modus nicht erfüllt werden können.

Ruft den aktuellen Modus ab:

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

 Configuration for NetHSM localhost:8443:
 Unattended boot: off

Schalten Sie den Modus „Unattended Boot“ ein:

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

 Updated the unattended boot configuration for NetHSM localhost:8443

Benutzerverwaltung #

Rollen #

Die Aufgabentrennung kann durch die Verwendung verschiedener Rollen realisiert werden. Jedem auf dem NetHSM konfigurierten Benutzerkonto ist eine der folgenden Rollen zugewiesen. Nachfolgend finden Sie eine allgemeine Beschreibung der von jeder Rolle erlaubten Operationen. Endpunktspezifische Details entnehmen Sie bitte der REST-API-Dokumentation.

R-Verwalter: Ein Benutzerkonto mit dieser Rolle hat Zugriff auf alle von der REST-API bereitgestellten Operationen, mit Ausnahme der Schlüsselverwendungsoperationen, d. h. der Signierung und Entschlüsselung von Nachrichten.
R-Operator: Ein Benutzerkonto mit dieser Rolle hat Zugriff auf alle Schlüsselverwendungsvorgänge, eine schreibgeschützte Teilmenge der Schlüsselverwaltungsvorgänge und Benutzerverwaltungsvorgänge, die nur Änderungen am eigenen Konto zulassen.
R-Metrics: Ein Benutzerkonto mit dieser Rolle hat nur Zugriff auf schreibgeschützte Metrikoperationen.
R-Backup: Ein Benutzerkonto mit dieser Rolle hat nur Zugriff auf die Vorgänge, die zum Einleiten einer Systemsicherung erforderlich sind.

Hinweis: In einer zukünftigen Version können weitere Rollen eingeführt werden.

Anlegen & Löschen von Benutzern

Erstellen Sie nun einen neuen Benutzer mit der Rolle Operator, der zum Signieren und Entschlüsseln von Daten verwendet werden kann. Beachten Sie, dass der NetHSM eine zufällige Benutzer-ID zuweist, wenn wir sie nicht angeben.

$ 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"

Schlüsselverwaltung #

Schlüssel generieren #

In diesem Abschnitt wollen wir einen RSA-Schlüssel zum Entschlüsseln von Daten mit PKCS#1 und zum Signieren von Daten mit PSS mit SHA256 verwenden. Lassen Sie uns also einen neuen Schlüssel auf dem NetHSM generieren. Stellen Sie sicher, dass Sie den RSA-Algorithmus verwenden und die Schlüsselmechanismen RSA_Signature_PSS_SHA256 und RSA_Decryption_PKCS1 auswählen. Wenn Sie keine Schlüssel-ID angeben, generiert der NetHSM eine zufällige ID für den neuen Schlüssel.

$ 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

Schlüssel importieren #

Anstatt einen Schlüssel auf dem NetHSM zu generieren, können Sie auch vorhandene private Schlüssel in den NetHSM importieren:

$ 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

Schlüssel auflisten #

Um sicherzustellen, dass der Schlüssel erstellt wurde und die richtigen Algorithmus- und Mechanismuseinstellungen hat, können wir alle Schlüssel auf dem NetHSM abfragen:

$ 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

Schlüsseldetails anzeigen #

Wir können auch den öffentlichen Schlüssel des erzeugten Schlüsselpaares abfragen:

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

Um den Schlüssel mit OpenSSL verwenden zu können, exportieren wir ihn als PEM-Datei und speichern ihn als public.pem:

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

Wir können den Schlüssel mit OpenSSL untersuchen und ihn zur Verschlüsselung oder Signaturprüfung verwenden (wie im nächsten Abschnitt beschrieben):

$ 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-----

Schlüssel-Zertifikate #

Es ist möglich, Zertifikate für die auf einer NetHSM-Instanz gespeicherten Schlüssel zu setzen und abzufragen:

$ 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

Signieranforderungen für Schlüsselzertifikate #

Der NetHSM unterstützt die Erzeugung von Certificate Signing Requests (CSR) für die gespeicherten Schlüssel:

$ 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

Wichtige Vorgänge #

Wir können Daten für den auf dem NetHSM gespeicherten Schlüssel mit OpenSSL verschlüsseln. (public.pem ist die öffentliche Schlüsseldatei, die wir im Abschnitt Schlüsseldetails anzeigen erstellt haben).

$ 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!

Auf ähnliche Weise können wir Daten mit dem Schlüssel auf dem NetHSM signieren. Für RSA und ECDSA müssen wir zuerst einen Digest berechnen:

$ echo 'NetHSM rulez!' > data

$ openssl dgst -sha256 -binary data | base64 > data.digest

Dann können wir mit dem NetHSM eine Signatur aus diesem Digest erstellen:

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

Und dann verwenden Sie OpenSSL, um die Signatur zu überprüfen:

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

Verified OK

Erstellen von Backups #

Es ist möglich, ein Backup des NetHSM zu erstellen, das sowohl die Konfiguration als auch die gespeicherten Schlüssel erfasst. Um ein Backup zu erstellen, müssen Sie zunächst eine Backup-Passphrase festlegen, die zur Verschlüsselung der Backup-Datei verwendet wird:

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

Updated the backup passphrase for NetHSM localhost:8443

Nun müssen Sie einen Benutzer mit der Rolle R-Backup anlegen:

$ 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

Dann können Sie die Sicherung erzeugen und in eine Datei schreiben:

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

Backup for localhost:8443 written to /tmp/backup

Wiederherstellung von Backups #

Diese Sicherungsdatei kann auf einer unprovisionierten NetHSM-Instanz wiederhergestellt werden:

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

Backup restored on NetHSM localhost:8443

NetHSM aktualisieren #

Warnung

Durch die Installation eines Beta-Updates kann es zu Datenverlusten kommen!

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

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

Wenn Sie mit der Installation fortfahren möchten, können Sie das Update jetzt bestätigen:

$ nitropy nethsm --host $NETHSM_HOST     commit-update

Update successfully committed on NetHSM localhost:8443

Alternativ können Sie das Update auch abbrechen:

$ nitropy nethsm --host $NETHSM_HOST  cancel-update

Update successfully cancelled on NetHSM localhost:8443