Integratie#
Het hoofdstuk beschrijft processen voor verschillende taken en richt zich op alle gebruikersgroepen.
REST-API#
De primaire interface van NetHSM is een moderne REST-API die de beste prestaties en functionaliteit garandeert. De API-specificatie is beschikbaar in OpenAPI formaat, en kan worden geïnspecteerd en getest in de API browser.
PKCS#11#
De NetHSM ondersteunt de PKCS#11-standaard. Het vereiste stuurprogramma is beschikbaar in de repository. De repository bevat de broncode en bibliotheken voor verschillende besturingssystemen. De PKCS#11 gids beschrijft het gebruik in detail.
Ontwikkeling en Testen#
Een publieke NetHSM demo-instantie is beschikbaar op nethsmdemo.nitrokey.com. Deze wordt elke acht uur gereset (CET 6:00, 14:00, 22:00). Gebruiker “admin”, wachtwoord “adminadmin”, ontgrendelingswachtwoord “unlockunlock”.
U kunt de NetHSM ook draaien als een Docker container lokaal.
De container kan als volgt worden uitgevoerd.
$ sudo docker run --rm -ti -p8443:8443 nitrokey/nethsm:testing
$ podman run --rm -ti -p8443:8443 docker.io/nitrokey/nethsm:testing
Dit zal NetHSM draaien als een Unix proces in de container en de REST API op poort 8443 beschikbaar maken via het HTTPS protocol.
Naast het draaien van de NetHSM als een Unix proces kan het draaien als een unikernel ondersteund door KVM.
De container kan als volgt worden uitgevoerd.
$ docker run -ti --rm -p 8443:8443 --device /dev/net/tun --device /dev/kvm --cap-add=NET_ADMIN nitrokey/nethsm:testing
Dit zal NetHSM draaien als een unikernel binnen een KVM virtuele machine. De container zal de REST API, via het HTTPS protocol, beschikbaar maken op de interface tap200 met het IP adres 192.168.1.100 en poort 8443.
Belangrijk
De container gebruikt een zelfondertekend TLS-certificaat. Zorg ervoor dat u de juiste verbindingsinstellingen gebruikt om een verbinding tot stand te brengen. Zie hoofdstuk NetHSM introductie voor meer informatie.
Integratie in aangepaste toepassing#
Om de NetHSM te integreren in eigen toepassingen, zijn er clientbibliotheken beschikbaar voor bijna alle programmeertalen. Hier zijn bibliotheken voor Python en Rust evenals deze derde partij Rust crate. Voor alle andere programmeertalen raden we aan OpenAPI Generator te gebruiken.
De lijst van alle beschikbare talen kan als volgt worden opgevraagd.
$ docker run --rm -ti openapitools/openapi-generator-cli list -i stable
$ podman run --rm -ti openapitools/openapi-generator-cli list -i stable
De NetHSM-client kan als volgt voor uw programmeertaal worden gegenereerd.
$ 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
$ podman 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
De gegenereerde client code, in dit voorbeeld JavaScript, wordt aangemaakt in de ./out/ directory. Deze map bevat ook de nodige documentatie over het gebruik ervan.
Belangrijk
Als Podman wordt gebruikt met handhaving van SELinux, kan een labeling van de volumemount nodig zijn. De modus van SELinux kan worden opgevraagd met sestatus |grep "Current mode". Als de modus is ingesteld op enforcing, is een wijziging van de context vereist. In dit geval moet de volume mount worden gepostfixed met :z, wat resulteert in -v "${PWD}/out:/out:z".
Opdrachtregelinterface#
Gebruikers kunnen een NetHSM beheren en gebruiken met een speciale commandoregelinterface (CLI). Nitrokey biedt nitropy, die wordt gedistribueerd in de Python gebaseerde pynitrokey. Met nethsm bestaat er een alternatieve applicatie van derden, die is ontwikkeld in het Rust crate nethsm-cli.