PKCS#11 mit pkcs11-Werkzeug#

Dieser Leitfaden beschreibt die Verwendung des PKCS#11-Treibers für den NetHSM. Der Leitfaden verwendet Tools von OpenSC. Bitte lesen Sie deren Dokumentation, um zu erfahren, wie Sie sie auf Ihrem Betriebssystem verwenden können.

Wichtig

Bei diesem Treiber handelt es sich noch um eine frühe Proof-of-Concept-Implementierung, die nur die Funktionen implementiert, die für den Betrieb von TLS-Servern erforderlich sind.

Installation#

Vorkompilierte Bibliothek installieren#

Laden Sie ein Archiv mit der neuesten Version von der Seite releases des Repositorys herunter. Verwenden Sie das Versionsarchiv, das den Namen Ihres Betriebssystems im Titel enthält.
Extrahieren Sie die Dateien aus dem heruntergeladenen Archiv mit einem Archivierungsprogramm Ihrer Wahl.
Kopieren Sie die entpackte Bibliothek in den entsprechenden Pfad Ihres Betriebssystems. Der Pfad hängt von Ihrer Installation und Konfiguration von OpenSC ab.

Kompilieren aus dem Quellcode#

Wichtig

Dieser Treiber kann nur mit dem offiziellen Go-Compiler kompiliert werden. Verwenden Sie nicht den GNU Go Compiler (GCC-Go). Bitte besuchen Sie die Website ` <https://go.dev/doc/install>` __, um zu erfahren, wie Sie ihn installieren.

Laden Sie ein Archiv mit der neuesten Version von der Seite releases des Repositorys herunter. Verwenden Sie das Versionsarchiv, das im Titel „Source Code“ enthält.
Extrahieren Sie die Dateien aus dem heruntergeladenen Archiv mit einem Archivierungsprogramm Ihrer Wahl.
Führen Sie in dem Verzeichnis mit dem extrahierten Quellcode den folgenden Befehl aus, um die Bibliothek zu kompilieren.
./build.sh
./build.sh
Kopieren Sie die entpackte Bibliothek in den entsprechenden Pfad Ihres Betriebssystems. Der Pfad hängt von Ihrer Installation und Konfiguration von OpenSC ab.

Konfiguration#

Die Konfigurationsdatei p11nethsm.conf wird benötigt und dient zur Konfiguration der Verbindung zwischen dem PKCS#11-Treiber und dem NetHSM.

Eine Beispielkonfigurationsdatei sieht wie folgt aus.

YAML 1.1
---
p11nethsm:
  logfile: /tmp/p11nethsm.log
  maxsessioncount: 5
  debug: true
  slots:
  - label: NetHSM1
    description: NetHSM Zone A
    url: "https://nethsmdemo.nitrokey.com/api/v1"
    # certSHA256:
    #   - "0C:66:DC:EB:4D:12:C3:24:FC:82:F4:1D:4C:16:44:12:1D:00:79:FF:36:96:65:E2:21:C4:36:94:F7:8E:22:89"
    user: "operator"
    password: "env:NETHSM_PASS"

Ändern Sie die Konfigurationsdatei p11nethsm.conf entsprechend Ihrer Umgebung.

Die Konfigurationsdatei kann mehrere Slots innerhalb des Arrays „slots“ enthalten. Die Slots stehen für mehrere NetHSM-Einsätze. Das Feld „label“ eines Slots muss einen eindeutigen Namen enthalten. Die Schlüssel url, user und password sind obligatorisch. Aus Sicherheitsgründen wird empfohlen, das Passwort in einer Umgebungsvariablen zu übergeben. Hierfür wird env:NETHSM_PASS im Schlüssel password übergeben, wobei NETHSM_PASS der Name der Umgebungsvariablen ist, die das Passwort enthält. Der Schluessel certSHA256 muss gesetzt werden, wenn das TLS-Zertifikat nicht von einer Zertifizierungsstelle (CA) signiert ist, die im Zertifikatspeicher des Betriebssystems enthalten ist.

Die Konfigurationsdatei muss entweder in den folgenden Pfaden oder in dem Verzeichnis, in dem die Anwendung ausgeführt wird, gespeichert werden.

$HOME/.nitrokey
/etc/nitrokey/

Schlüsselverwaltung#

Infos#

Zeigt Informationen über die cryptoki-Version und den PKCS#11-Treiber an.

$ pkcs11-tool --module p11nethsm.so --show-info

Cryptoki version 2.40
Manufacturer     Nitrokey GmbH
Library          NetHSM PKCS#11 module (ver 0.1)
Using slot 0 with a present token (0x0)

Slots auflisten#

Die Informationen über die verfügbaren Steckplätze. Die aufgelisteten Slots hängen von der Konfiguration des Slot-Arrays in der Konfigurationsdatei p11nethsm.conf ab. Um mehr über die Konfiguration von Slots zu erfahren, lesen Sie bitte das Kapitel Konfiguration <pkcs11_with_pkcs11-tool.html#configuration>`_.

$ pkcs11-tool --module p11nethsm.so --list-slots

Available slots:
Slot 0 (0x0): NetHSM Zone A
  token label        : NetHSM1
  token manufacturer : Nitrokey GmbH
  token model        : NetHSM
  token flags        : rng, token initialized, PIN initialized, readonly
  hardware version   : 0.1
  firmware version   : 0.1
  serial num         : 0
  pin min/max        : 3/256

Bemerkung

Wenn Ihre Konfiguration mehr als einen Slot unterstützt, müssen Sie möglicherweise die Option –slot <arg> in den pkcs11-tool-Befehlen hinzufügen, um den richtigen Slot zu verwenden.

Schlüssel generieren#

Erzeugen Sie ein Schlüsselpaar und speichern Sie es auf dem NetHSM.

Bemerkung

Der PKCS#11-Treiber unterstützt diese Funktion derzeit nicht. Ein Schlüsselpaar kann mit nitropy oder einer REST-API-Anfrage erzeugt werden. Weitere Informationen zum Erzeugen eines Schlüssels finden Sie im Kapitel Schlüssel generieren.

Schlüssel auflisten#

Anzeigen von Informationen über die Schlüssel und Zertifikate im Key Store auf einem NetHSM.

$ pkcs11-tool --module p11nethsm.so --list-objects

Using slot 0 with a present token (0x0)
Private Key Object; RSA
  label:      myFirstKey
  ID:         6d7946697273744b6579
  Usage:      decrypt, sign
  Access:     sensitive, always sensitive, never extractable
Public Key Object; RSA 0 bits
  label:      myFirstKey
  ID:         6d7946697273744b6579
  Usage:      none
  Access:     none

Tasten lesen#

Lesen von Schlüsseln und Zertifikaten aus dem Key Store auf einem NetHSM. Es ist nicht möglich, private Schlüssel aus dem NetHSM zu lesen.

Der öffentliche Schlüssel eines Schlüsselpaares kann wie folgt gelesen werden.

$ pkcs11-tool --module p11nethsm.so --read-object --type pubkey --label myFirstKey -o public.key

Das Zertifikat eines Schlüsselpaares kann wie folgt gelesen werden.

$ pkcs11-tool --module p11nethsm.so --read-object --type cert --label myFirstKey -o public.key

Die zurückgegebenen Zertifikate oder öffentlichen Schlüssel sind ASN.1-kodiert. Die Daten können mit dem Tool dumpasn1 entschlüsselt werden, da sie Daten im DER-Format enthalten. Das DER-Format kann mit OpenSSL in das PEM-Format umgewandelt werden.

Tasten schreiben#

Schreiben Sie Schlüssel und Zertifikate in den Key Store auf einem NetHSM.

Der private Schlüssel eines Schlüsselpaares kann wie folgt geschrieben werden.

$ pkcs11-tool --module p11nethsm.so --write-object secret.key --type privkey --label myFirstKey

Der öffentliche Schlüssel eines Schlüsselpaares kann wie folgt geschrieben werden.

$ pkcs11-tool --module p11nethsm.so --write-object public.key --type pubkey --label myFirstKey

Das Zertifikat eines Schlüsselpaares kann wie folgt geschrieben werden.

$ pkcs11-tool --module p11nethsm.so --write-object cert.pub --type cert --label myFirstKey

Wichtige Vorgänge#

Verschlüsseln Sie#

Der NetHSM kann Daten nicht mit asymmetrischen Schlüsseln verschlüsseln, aber er stellt den öffentlichen Schlüssel zur Verfügung, der zur Verschlüsselung verwendet werden kann. Bitte lesen Sie das Kapitel Show Key Details, oder rufen Sie den Schlüssel wie in Kapitel Read Keys <pkcs11_with_pkcs11.html#read-keys> beschrieben ab, um mehr darüber zu erfahren, wie man den öffentlichen Schlüssel abruft. Das Beispiel setzt den öffentlichen Schlüssel in der Datei public.pem voraus.

Daten können mit OpenSSL wie folgt verschlüsselt werden.

$ echo 'NetHSM rulez!' | openssl pkeyutl -encrypt -pubin \
   -inkey public.pem \
   -pkeyopt rsa_padding_mode:oaep \
   -pkeyopt rsa_oaep_md:sha512 \
   -pkeyopt rsa_mgf1_md:sha512 \
   -out encrypted.data

Entschlüsseln#

Der NetHSM kann Daten für einen privaten Schlüssel entschlüsseln, der im Key Store auf dem NetHSM gespeichert ist. Dieses Beispiel verwendet die verschlüsselte Nachricht aus dem vorherigen Kapitel Encrypt.

$ pkcs11-tool --module p11nethsm.so --decrypt \
   --mechanism RSA-PKCS-OAEP \
   --input-file encrypted.data \
   --label myFirstKey \
   --hash-algorithm SHA512

NetHSM rulez!

Unterschrift#

Der NetHSM kann Daten für einen privaten Schlüssel signieren, der im Schlüsselspeicher des NetHSM gespeichert ist. Für Signaturen mit einem RSA- und ECDSA-Schlüssel muss zunächst ein Digest berechnet werden.

Um einen Digest zu berechnen, werden zunächst die Daten benötigt. Eine Nachricht wird wie folgt erstellt.

$ echo 'NetHSM rulez!' | pkcs11-tool --module p11nethsm.so \
   --sign \
   --mechanism SHA512-RSA-PKCS-PSS \
   --output-file sig.data \
   --label myFirstKey

Die erstellte Signatur kann mit OpenSSL wie folgt überprüft werden.

$ echo 'NetHSM rulez!' | openssl dgst -keyform PEM \
   -verify public.pem \
   -sha512 \
   -sigopt rsa_padding_mode:pss \
   -sigopt rsa_pss_saltlen:-1 \
   -signature sig.data