Toegang tot een NetHSM met behulp van de REST API#

Initialisatie
Gebruikersbeheer
- Een gebruiker aanmaken
Sleutelbeheer
Belangrijkste operaties
- Decryptie
- Ondertekening
Back-ups
Updates

Deze tutorial demonstreert hoe je toegang krijgt tot de NetHMS via de REST API. De interface is hier gedocumenteerd en de’s specificatie is beschikbaar als RAML en als OpenAPI (Swagger).

Notitie

Als je een NetHSM demo instance met een zelfondertekend certificaat gebruikt, bijvoorbeeld met het Docker image, moet u de --insecure/-k optie voor curl gebruiken om de certificaatcontrole over te slaan.

Notitie

Stel eerst de waarde van $NETHSM_HOST in op het IP-adres of de URL van je NetHSM. Onze demo server kan worden bereikt op https://nethsmdemo.nitrokey.com/

Laten we eerst eens kijken wat we hier hebben:

$ curl -i -w '\n' https://$NETHSM_HOST/api/v1/info

HTTP/1.1 200 OK
content-length: 45
content-type: application/json
date: Mon, 25 Jan 2021 21:00:27 GMT
etag: "7bab62510e05c332735624bc7a585a30"
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

{"vendor":"Nitrokey GmbH","product":"NetHSM"}

Notitie

De -i/–include optie zorgt ervoor dat curl de HTTP status code en de antwoord headers afdrukt. De -w ‘n’/–write-out ‘n’ optie voegt een newline toe na de respons body.

Kijk wat de status van het apparaat is:

$ curl -i -w '\n' https://$NETHSM_HOST/api/v1/health/state

HTTP/1.1 200 OK
cache-control: no-cache
content-length: 25
content-type: application/json
date: Mon, 25 Jan 2021 20:57:32 GMT
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

{"state":"Unprovisioned"}

Initialisatie #

Een nieuwe NetHSM moet eerst voorzien worden van passphrases en de huidige tijd. De Admin Passphrase is de passphrase van de Administrator, die de supergebruiker van de NetHSM is. De Unlock Passphrase wordt gebruikt om de vertrouwelijke gegevensopslag van de NetHSM te versleutelen.

Notitie

De NetHSM demo instance op nethsmdemo.nitrokey.com is al voorzien.

$ curl -i -w '\n' -X POST https://$NETHSM_HOST/api/v1/provision \
-H "content-type: application/json" \
-d "{ adminPassphrase: \"adminPassphrase\", unlockPassphrase: \"unlockPassphrase\", \
systemTime: \"$(date --utc -Iseconds)\"}"

HTTP/1.1 204 No Content
cache-control: no-cache
content-type: application/json
date: Wed, 11 Nov 2020 16:35:44 GMT
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

NetHSM kan worden gebruikt in Attended Boot-modus en Unattended Boot-modus.

In de modus Attended Boot moet bij elke start de Unlock Passphrase worden ingevoerd, die wordt gebruikt om de opgeslagen gegevens te versleutelen. Om veiligheidsredenen wordt deze modus aanbevolen.
In de modus Unattended Boot is geen ontgrendelingspassphrase vereist, daarom kan de NetHSM zonder toezicht starten en wordt de gegevensopslag onversleuteld opgeslagen. Gebruik deze modus als niet aan uw beschikbaarheidseisen kan worden voldaan met de modus Attended Boot.

De huidige modus opvragen:

$ curl -i -w '\n' -u admin \
https://$NETHSM_HOST/api/v1/config/unattended-boot

HTTP/1.1 200 OK
content-length: 16
content-type: application/json
date: Wed, 21 Apr 2021 10:20:55 GMT
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

{"status":"off"}

Schakel over naar Unattended Boot mode:

$ curl -i -w '\n' -X PUT -H "content-type: application/json" \
https://$NETHSM_HOST/api/v1/config/unattended-boot -d "{ status: \"on\"}"

HTTP/1.1 204 No Content
content-type: application/json
date: Wed, 21 Apr 2021 10:24:25 GMT
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

Of schakel terug naar Attended Boot mode:

$ curl -i -w '\n' -u admin -X PUT -H "content-type: application/json" \
https://$NETHSM_HOST/api/v1/config/unattended-boot -d "{ status: \"off\"}"

HTTP/1.1 204 No Content
content-type: application/json
date: Wed, 21 Apr 2021 10:24:53 GMT
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

Gebruikersbeheer #

Een gebruiker aanmaken #

Maak nu een nieuwe gebruiker aan met de operator rol die gebruikt kan worden om gegevens te ondertekenen en te ontsleutelen. Merk op dat de NetHSM een willekeurige gebruikers-ID toekent als we die niet specificeren.

$ curl -i -w '\n' -u admin \
"https://$NETHSM_HOST/api/v1/users/operator" -X PUT \
-H "content-type: application/json" -d "{\"realName\": \"Jane User\", \
\"role\": \"Operator\", \"passphrase\": \"opPassphrase\"}"

HTTP/1.1 201 Created
content-length: 0
content-type: application/json
date: Wed, 21 Apr 2021 10:25:27 GMT
location: /api/v1/users/operator
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

Sleutelbeheer #

De NetHSM ondersteunt RSA-, ED25519- en ECDSA-sleutels. Bij het aanmaken van een sleutel moet u zowel het sleutelalgoritme als de te gebruiken sleutelmechanismen selecteren. RSA-sleutels kunnen worden gebruikt voor ontcijfering (met de modi raw, PKCS #1 en OAEP met MD5, SHA1, SHA224, SHA256, SHA384 of SHA512) en voor handtekeningen (met de modi PKCS #1 en PSS met MD5, SHA1, SHA224, SHA256, SHA384 of SHA512). De andere algoritmen ondersteunen alleen het handtekeningmechanisme.

Voor een volledige lijst van beschikbare sleutelalgoritmen en sleutelmechanismen, zie de API-documentatie voor de types KeyAlgorithm en KeyMechanism.

Genereer sleutels #

In deze handleiding willen we een RSA sleutel gebruiken om gegevens te decoderen met PKCS #1 en om gegevens te ondertekenen met PSS met SHA256. Laten we dus een nieuwe sleutel op de NetHSM genereren. Zorg ervoor dat u het RSA algoritme gebruikt en dat u het RSA_Signature_PSS_SHA256 en RSA_Decryption_PKCS1 sleutelmechanismen selecteert. Als u geen sleutel-ID opgeeft, genereert de NetHSM een willekeurige ID voor de nieuwe sleutel.

$ curl -i -w '\n' -u admin -X POST \
https://$NETHSM_HOST/api/v1/keys/generate -H "content-type: application/json" \
-d "{ \"mechanisms\": [ \"RSA_Signature_PSS_SHA256\", \"RSA_Decryption_PKCS1\" ], \
\"type\": \"RSA\",  \"length\": 2048,  \"id\": \"myFirstKey\"}"

HTTP/1.1 201 Created
cache-control: no-cache
content-length: 0
content-type: application/json
date: Tue, 26 Jan 2021 05:54:09 GMT
location: /api/v1/keys/0ead0d9dd849cecf845c
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

Sleutels importeren #

In plaats van een sleutel op de NetHSM te genereren, kunt u ook bestaande privé-sleutels in de NetHSM importeren:

$ curl -i -w '\n' -u admin -X PUT \
https://$NETHSM_HOST/api/v1/keys/mySecondKey -H "content-type: application/json" \
-d "{ \"mechanisms\": [ \"RSA_Signature_PSS_SHA256\", \"RSA_Decryption_PKCS1\" ], \
\"type\": \"RSA\",  \"key\": {\"primeP\": \"AOnWFZ+JrI/xOXJU04uYCZOiPVUWd6CSbVseEYrYQYxc7dVroePshz29tc+VEOUP5T0O8lXMEkjFAwjW6C9QTAsPyl6jwyOQluMRIkdN4/7BAg3HAMuGd7VmkGyYrnZWW54sLWp1JD6XJG33kF+9OSar9ETPoVyBgK5punfiUFEL\", \"primeQ\": \"ANT1kWDdP9hZoFKT49dwdM/S+3ZDnxQa7kZk9p+JKU5RaU9e8pS2GOJljHwkES1FH6CUGeIaUi81tRKe2XZhe/163sEyMcxkaaRbBbTc1v6ZDKILFKKt4eX7LAQfhL/iFlgi6pcyUM8QDrm1QeFgGz11ChM0JuQw1WwkX06lg8iv\", \"publicExponent\": \"AQAB\"}}"

HTTP/1.1 204 No Content
content-type: application/json
date: Wed, 21 Apr 2021 10:37:23 GMT
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

Lijst Sleutels #

Om er zeker van te zijn dat de sleutel is aangemaakt en de juiste algoritme- en mechanisme-instellingen heeft, kunnen we alle sleutels op de NetHSM opvragen:

$ curl -i -w '\n' -u admin
HTTP/1.1 200 OK
content-length: 39
content-type: application/json
date: Tue, 26 Jan 2021 05:56:24 GMT
etag: "34353234366432333063663739313939346635316666343937333564653434333937613237626139"
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

[{"key":"myFirstKey"},{"key":"mySecondKey"}]

Toon sleutel details #

We kunnen ook de publieke sleutel van het gegenereerde sleutelpaar opvragen:

$ curl -s -w '\n' -u admin https://$NETHSM_HOST/api/v1/keys/myFirstKey

{"mechanisms":["RSA_Decryption_PKCS1","RSA_Signature_PSS_SHA256"],"type":"RSA","modulus":"td583uBYRfO7qtvPoQF7liUh8gq3zckCk9LpCfblx2S0HdOvButfD4TyH4EMiZj3NhEoq18BZhqhxTL22UyNJwYJd2tCF4EbgTaj/Z3LeCPoGN5LjadFCsYriPeHsdnuLmTK6KsmTAP/CWJ+u3LesU5bCGWbDnPjv2WaLTeiMuNw1347gj1drft8jFA9SmOFjZxM9pq2Hk1nQSYpeAPCnigC7hLwAWgzKqVQv/J7VVWat3ke/jOrxFiRDFIeC3qxtBs6T7GYwqmsxkxgqKDljTAH4qMrC9vgVbbFPffe8UgmtDfvQ0ghP57b3HYZDON90MJ2qrU944E74g+ua6unTw==","publicExponent":"AQAB","operations":0}

Om de sleutel met OpenSSL te kunnen gebruiken, exporteren we hem als een PEM-bestand en slaan we hem op als public.pem:

$ curl -u operator -X GET \
https://$NETHSM_HOST/api/v1/keys/myFirstKey/public.pem -o public.pem

We kunnen de sleutel inspecteren met openssl en hem gebruiken voor encryptie of handtekening verificatie (zoals beschreven in de volgende sectie):

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

Sleutelcertificaten #

Het is mogelijk certificaten in te stellen en op te vragen voor de sleutels die op een NetHSM-instantie zijn opgeslagen:

$ curl -i -w '\n' -u admin -X PUT \
https://$NETHSM_HOST/api/v1/keys/myFirstKey/cert -H "content-type: application/x-pem-file" \
--data-binary @/tmp/cert.pem

HTTP/1.1 201 Created
content-length: 0
content-type: text/html
date: Thu, 20 May 2021 19:15:39 GMT
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

 $ curl -s -w '\n' -u operator -X GET \
https://$NETHSM_HOST/api/v1/keys/myFirstKey/cert > /tmp/cert.pem

$ curl -i -w '\n' -u admin -X DELETE \
https://$NETHSM_HOST/api/v1/keys/myFirstKey/cert

HTTP/1.1 204 No Content
content-type: text/html
date: Thu, 20 May 2021 19:14:45 GMT
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

Verzoeken om ondertekening van sleutelcertificaten #

De NetHSM ondersteunt het genereren van Certificate Signing Requests (CSR) voor de opgeslagen sleutels:

$ curl -s -w '\n' -u operator -X POST \
https://$NETHSM_HOST/api/v1/keys/myFirstKey/csr.pem -H "content-type: application/json" \
-d "{ \"countryName\": \"DE\", \"stateOrProvinceName\": \"BE\", \
\"localityName\": \"Berlin\", \"organizationName\": \"ACME\", \
\"organizationalUnitName\": \"IT\", \"commonName\": \"example.com\", \
\"emailAddress\": \"it@example.com\" }" > /tmp/cert.pem

Belangrijkste operaties #

Decryptie #

We kunnen gegevens versleutelen voor de sleutel die op de NetHSM is opgeslagen met openssl. (public.pem is het bestand met de openbare sleutel dat we hebben gemaakt in de Show Key Details sectie).

$ echo 'NetHSM rulez!' | OpenSSL rsautl -encrypt -inkey public.pem -pubin | base64 > data.crypt

Nu kunnen we de NetHSM gebruiken om de gegevens te decoderen:

$ curl -s -u operator -X POST \
https://$NETHSM_HOST/api/v1/keys/myFirstKey/decrypt -H "content-type: application/json" \
-d "{ \"mode\": \"PKCS1\", \"encrypted\": \"$(cat data.crypt)\"}" | \
jq -r .decrypted | base64 -d

NetHSM rulez!

Ondertekening #

Op dezelfde manier kunnen wij gegevens ondertekenen met de sleutel op de NetHSM. Voor RSA en ECDSA moeten we eerst een digest berekenen:

$ echo 'NetHSM rulez!' > data

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

Dan kunnen we van deze digest een handtekening maken met de NetHSM:

$ curl -s -u operator -X POST \
https://$NETHSM_HOST/api/v1/keys/myFirstKey/sign -H "content-type: application/json" \
-d "{ \"mode\": \"PSS_SHA256\", \"message\": \"$(cat data.digest)\"}" | \
jq -r .signature | base64 -d > data.sig

En gebruik dan OpenSSL om de handtekening te verifiëren:

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

Verified OK

Back-ups #

Het is mogelijk om een backup van de NetHSM te maken die zowel de configuratie als de opgeslagen sleutels vastlegt. Om een backup te maken, moet eerst een backup-wachtzin worden ingesteld die wordt gebruikt om het backup-bestand te versleutelen:

$ curl -i -w '\n' -u admin -X PUT \
https://$NETHSM_HOST/api/v1/config/backup-passphrase -H "content-type: application/json" \
-d "{\"passphrase\": \"backupencryptionkey\"}"

HTTP/2 204
server: nginx/1.14.2
date: Sat, 08 May 2021 10:26:36 GMT
cache-control: no-cache
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language
strict-transport-security: max-age=63072000; includeSubDomains; preload
x-frame-options: DENY
x-content-type-options: nosniff
x-xss-protection: 1; mode=block
x-permitted-cross-domain-policies: none

Nu moet je een gebruiker aanmaken met de R-Backup rol:

$ curl -i -w '\n' -u admin -X PUT \
https://$NETHSM_HOST/api/v1/users/backup -H "content-type: application/json" \
-d "{\"realName\": \"Backup User\", \"role\": \"Backup\", \
\"passphrase\": \"backupPassphrase\"}"

HTTP/2 201
server: nginx/1.14.2
date: Sat, 08 May 2021 10:30:45 GMT
content-type: application/json
content-length: 0
location: /api/v1/users/backup
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language
strict-transport-security: max-age=63072000; includeSubDomains; preload
x-frame-options: DENY
x-content-type-options: nosniff
x-xss-protection: 1; mode=block
x-permitted-cross-domain-policies: none

Haal de backup en sla het op in een bestand:

$ curl -s -u backup -X POST \
https://$NETHSM_HOST/api/v1/system/backup > /tmp/nethsm-backup

Dit backupbestand kan worden teruggezet op een niet-geprovisioneerde NetHSM-instantie:

$ curl -i -X POST \
"https://$NETHSM_HOST/api/v1/system/restore?backupPassphrase=backupencryptionkey&systemTime=$(date --utc +"%Y-%m-%dT%H:%M:%SZ")" \
 --data-binary @/tmp/nethsm-backup

HTTP/1.1 204 No Content
cache-control: no-cache
content-type: application/json
date: Sat, 08 May 2021 10:59:19 GMT
vary: Accept, Accept-Encoding, Accept-Charset, Accept-Language

Updates #

Updates voor de NetHSM kunnen in twee stappen worden geïnstalleerd. Eerst moet de update-image naar de NetHSM worden geüpload. De image wordt vervolgens gecontroleerd en gevalideerd. Als de validatie succesvol is, worden de release notes voor de update door de NetHSM geretourneerd:

$ curl -i -w '\n' -u admin -X POST  \
https://$NETHSM_HOST/api/v1/system/update --data-binary "@/tmp/nethsm-update.img.cpio"

Als u verder wilt gaan met de installatie, kunt u de update nu vastleggen:

$ curl -i -w '\n' -u admin -X POST  \
https://$NETHSM_HOST/api/v1/system/commit-update

U kunt de update ook annuleren:

$ curl -i -w '\n' -u admin -X POST  \
https://$NETHSM_HOST/api/v1/system/cancel-update