Integration#

Das Kapitel beschreibt Prozesse für verschiedene Aufgaben und richtet sich an alle Benutzergruppen.

PKCS#11-Treiber#

Wichtig

Dieser Treiber ist noch eine frühe Proof-of-Concept-Implementierung, die nur die Funktionen implementiert, die für den Betrieb von TLS-Servern, wie z.B. einem HTTPS-Server, notwendig sind.

  1. Laden Sie den PKCS#11-Treiber für NetHSM herunter.

  2. Ändern Sie die Konfigurationsdatei p11nethsm.conf entsprechend Ihrer Einrichtung (z.B. Adresse, Betreibername) und speichern Sie sie in $HOME/.nitrokey, /etc/nitrokey/, oder in dem Ordner, in dem Ihre Anwendung ausgeführt wird.

Verschlüsseln & Entschlüsseln#

Nachdem Sie einen Schlüssel (hier: ID 42) mit dem entsprechenden Mechanismus erstellt haben, können Sie ihn für die Ver- und Entschlüsselung verwenden, aber zuerst sollten Sie den Schlüssel erstellen:

$ KEYID=42

$ HEXID=$(echo ${KEYID}'\c' | xxd -ps)

$ curl -s -X GET https://nethsmdemo.nitrokey.com/api/v1/keys/$KEYID/public.pem -o public.pem

Jetzt können Sie verschlüsseln:

$ 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

Und entschlüsseln:

$ pkcs11-tool --module p11nethsm.so -v --decrypt --mechanism RSA-PKCS-OAEP --input-file encrypted.data --id $HEXID --hash-algorithm SHA512

Signieren#

Erstellen Sie zunächst den Schlüssel neu:

$ KEYID=23

$ HEXID=$(echo ${KEYID}'\c' | xxd -ps)

$ curl -s -X GET https://nethsmdemo.nitrokey.com/api/v1/keys/$KEYID/public.pem -o public.pem

Nachdem Sie einen Schlüssel (hier: ID 23) mit dem entsprechenden Mechanismus erstellt haben, können Sie ihn zum Signieren verwenden:

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

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

Entwicklung und Prüfung#

Eine öffentliche NetHSM-Demoinstanz ist unter nethsmdemo.nitrokey.com verfügbar.

Alternativ können Sie den NetHSM auch als Docker-Container lokal ausführen. Der NetHSM-Container erfordert eine verschachtelte Virtualisierung für eine starke Trennung mit anderen Containern. Um einen NetHSM-Container zu starten, benötigen Sie also einen Linux-Host, auf dem /dev/kvm verfügbar ist. Führen Sie diesen Befehl aus:

$ sudo docker run --rm -ti --device=/dev/net/tun:/dev/net/tun --cap-add=NET_ADMIN -p8443:8443 nitrokey/nethsm:testing

Integration in benutzerdefinierte Anwendung#

Um das NetHSM in eigene Anwendungen zu integrieren, sind Client-Bibliotheken für fast alle Programmiersprachen verfügbar. Wir empfehlen daher die Verwendung von OpenAPI Generator.

Die Liste aller verfügbaren Sprachen kann wie folgt abgerufen werden.

$ docker run --pull --rm -ti openapitools/openapi-generator-cli list -i stable

Der NetHSM-Client kann wie folgt für Ihre Programmiersprache generiert werden.

$ docker run --rm -ti -v "${PWD}/out:/out" openapitools/openapi-generator-cli generate -i=https://nethsmdemo.nitrokey.com/api_docs/nethsm-api.yaml -o out -g javascript

Der generierte Client-Code, in diesem Beispiel JavaScript, wird im Verzeichnis ./out/ erstellt. Dieser Ordner enthält auch die notwendige Dokumentation, wie er zu verwenden ist.

REST-API#

Die NetHSM’s API-Spezifikation ist im OpenAPI-Format verfügbar und kann im API-Browser eingesehen und getestet werden.