Adgang til en NetHSM ved hjælp af REST API’et#

Initialisering
Brugerstyring
- Opret en bruger
Nøglehåndtering
Vigtigste operationer
- Dekryptering
- Underskrift
Sikkerhedskopiering
Opdateringer

This tutorial demonstrates how to access the NetHMS via REST API. The interface is documented here, and its specification is available as RAML and as OpenAPI (Swagger).

Bemærk

Hvis du bruger en NetHSM-demoinstans med et selvsigneret certifikat, f.eks. ved hjælp af Docker-aftrykket, skal du bruge indstillingen --insecure/-k for curl for at springe certifikatkontrollen over.

Bemærk

Indstil først værdien af $NETHSM_HOST til IP-adressen eller URL-adressen for din NetHSM. Vores demoserver kan nås på https://nethsmdemo.nitrokey.com/

Lad os først se, hvad vi har her:

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

Bemærk

Indstillingen -i/–include får curl til at udskrive HTTP-statuskoden og svarheaderene. Indstillingen -w ›n‹/–write-out ›n‹ tilføjer en ny linje efter svarteksten.

Se, hvad enhedens status er:

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

Initialisering #

En ny NetHSM skal først forsynes med adgangsfraser og det aktuelle tidspunkt. Admin Passphrase er Administrator’s passphrase, som er superbrugeren af NetHSM’en. Unlock Passphrase bruges til at kryptere NetHSM’s fortrolige datalager.

Bemærk

NetHSM-demoinstansen på nethsmdemo.nitrokey.com er allerede tilvejebragt.

$ 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 bruges i Attended Boot-tilstand og Unattended Boot-tilstand.

I Attended Boot-tilstand skal Unlock Passphrase indtastes ved hver start, som bruges til at kryptere datalageret. Af sikkerhedshensyn anbefales denne tilstand.
I Unattended Boot-tilstand kræves der ingen Unlock Passphrase, og derfor kan NetHSM starte uden opsyn, og datalageret gemmes ukrypteret. Brug denne tilstand, hvis dine tilgængelighedskrav ikke kan opfyldes med Attended Boot-tilstand.

Henter den aktuelle tilstand:

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

Skift til Unattended Boot-tilstand:

$ 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

Eller skift tilbage til Attended Boot-tilstand:

$ 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

Brugerstyring #

Opret en bruger #

Opret nu en ny bruger med operatørrollen, som kan bruges til at signere og dekryptere data. Bemærk, at NetHSM tildeler et tilfældigt bruger-id, hvis vi ikke angiver det.

$ 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

Nøglehåndtering #

NetHSM understøtter RSA-, ED25519- og ECDSA-nøgler. Når du opretter en nøgle, skal du vælge både den nøglealgoritme og de nøglemekanismer, der skal anvendes. RSA-nøgler kan anvendes til dekryptering (med tilstanden raw, PKCS #1 og OAEP med MD5, SHA1, SHA224, SHA256, SHA384 eller SHA512) og til signaturer (med tilstanden PKCS #1 og PSS med MD5, SHA1, SHA224, SHA256, SHA384 eller SHA512). De andre algoritmer understøtter kun signaturmekanismen.

Du kan finde en komplet liste over tilgængelige nøglealgoritmer og nøglemekanismer i API-dokumentationen for typerne KeyAlgorithm og KeyMechanism.

Generere nøgler #

I denne vejledning ønsker vi at bruge en RSA-nøgle til at dekryptere data ved hjælp af PKCS #1 og til at signere data med PSS ved hjælp af SHA256. Så lad os generere en ny nøgle på NetHSM. Sørg for at bruge RSA-algoritmen og for at vælge RSA_Signature_PSS_SHA256 og RSA_Decryption_PKCS1-nøgleordningerne. Hvis du ikke angiver et nøgle-id, genererer NetHSM et tilfældigt id til den nye nøgle.

$ 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

Import af nøgler #

I stedet for at generere en nøgle på NetHSM kan du også importere eksisterende private nøgler til NetHSM:

$ 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

Liste over nøgler #

For at sikre, at nøglen er blevet oprettet og har de korrekte indstillinger for algoritme og mekanisme, kan vi spørge alle nøgler på NetHSM:

$ 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"}]

Vis nøgleoplysninger #

Vi kan også forespørge den offentlige nøgle for det genererede nøglepar:

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

For at kunne bruge nøglen med OpenSSL eksporterer vi den som en PEM-fil og gemmer den som public.pem:

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

Vi kan inspicere nøglen med openssl og bruge den til kryptering eller signaturverifikation (som beskrevet i næste afsnit):

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

Nøglecertifikater #

Det er muligt at indstille og forespørge certifikater for de nøgler, der er gemt på en NetHSM-instans:

$ 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

Anmodninger om signering af nøglecertifikater #

NetHSM understøtter generering af Certificate Signing Requests (CSR) for de lagrede nøgler:

$ 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

Vigtigste operationer #

Dekryptering #

Vi kan kryptere data for den nøgle, der er gemt på NetHSM, ved hjælp af openssl. (public.pem er den offentlige nøglefil, som vi oprettede i afsnittet Show Key Details).

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

Nu kan vi bruge NetHSM til at dekryptere dataene:

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

Underskrift #

På samme måde kan vi signere data ved hjælp af nøglen på NetHSM. For RSA og ECDSA skal vi først beregne en digest:

$ echo 'NetHSM rulez!' > data

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

Derefter kan vi oprette en signatur ud fra dette digest ved hjælp af 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

Brug derefter OpenSSL til at verificere signaturen:

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

Verified OK

Sikkerhedskopiering #

Det er muligt at lave en sikkerhedskopi af NetHSM, som både indeholder konfigurationen og de gemte nøgler. For at oprette en sikkerhedskopi skal du først indstille en sikkerhedskopi-passphrase, som bruges til at kryptere sikkerhedskopifilen:

$ 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 skal du oprette en bruger med rollen R-Backup:

$ 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

Hent sikkerhedskopien, og gem den i en fil:

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

Denne sikkerhedskopifil kan gendannes på en NetHSM-instans, der ikke er tilknyttet:

$ 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

Opdateringer #

Opdateringer til NetHSM kan installeres i en totrinsproces. Først skal du uploade opdateringsaftrykket til NetHSM. Derefter kontrolleres og valideres billedet. Hvis valideringen er vellykket, returnerer NetHSM udgivelsesbemærkningerne for opdateringen:

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

Hvis du vil fortsætte med installationen, kan du nu bekræfte opdateringen:

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

Alternativt kan du annullere opdateringen:

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