Integration#

Kapitlet beskriver processer för olika uppgifter och riktar sig till alla användargrupper.

PKCS#11-drivrutin#

Viktigt

Den här drivrutinen är fortfarande en tidig Proof of Concept-implementation som endast implementerar de funktioner som är nödvändiga för att driva TLS-servrar, som till exempel en HTTPS-server.

  1. Ladda ner PKCS#11-drivrutinen för NetHSM.

  2. Ändra konfigurationsfilen p11nethsm.conf enligt din inställning (t.ex. adress, operatörsnamn) och spara den i $HOME/.nitrokey, /etc/nitrokey/ eller i den mapp där programmet körs.

Kryptering och dekryptering#

När du har skapat en nyckel (här: ID 42) med den mekanism som anges kan du använda den för kryptering och dekryptering, men först måste du skapa nyckeln:

$ 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

Nu kan du kryptera:

$ 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

Och dekryptera:

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

Signering#

Först skapar du nyckeln på nytt:

$ 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

När du har skapat en nyckel (här: ID 23) med den mekanism som anges kan du använda den för signering:

$ 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

Utveckling och testning#

En offentlig NetHSM-demoinstans finns på nethsmdemo.nitrokey.com.

Alternativt kan du köra NetHSM som en Docker-behållare lokalt. NetHSM-behållaren kräver inbäddad virtualisering för stark separation med andra behållare. För att starta en NetHSM-container behöver du alltså en Linuxvärd med /dev/kvm tillgänglig. Utför det här kommandot:

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

Integrering i en anpassad applikation#

För att integrera NetHSM i egna anpassade applikationer finns klientbibliotek för nästan alla programmeringsspråk. Därför rekommenderar vi att man använder OpenAPI Generator.

Listan över alla tillgängliga språk kan hämtas på följande sätt.

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

NetHSM-klienten kan genereras för ditt programmeringsspråk på följande sätt.

$ 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

Den genererade klientkoden, i det här exemplet JavaScript, skapas i katalogen ./out/. Denna mapp innehåller också den nödvändiga dokumentationen om hur den ska användas.

REST-API#

NetHSM’s API-specifikation finns tillgänglig i OpenAPI-format, och kan inspekteras och testas i API-browser.