Accedere a un NetHSM usando l’API REST#

Inizializzazione
Gestione degli utenti
- Creare un utente
Gestione delle chiavi
Operazioni chiave
- Decrittazione
- Firma
Backups
Aggiornamenti

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).

Nota

Se usate un’istanza demo di NetHSM con un certificato autofirmato, per esempio usando l’immagine Docker, dovrai usare l’opzione --insecure/-k per curl per saltare il controllo del certificato.

Nota

Per prima cosa impostate il valore di $NETHSM_HOST sull’indirizzo IP o sull’URL del vostro NetHSM. Il nostro server demo è raggiungibile all’indirizzo https://nethsmdemo.nitrokey.com/

Per prima cosa, vediamo cosa abbiamo qui:

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

Nota

L’opzione -i/–include fa sì che curl stampi il codice di stato HTTP e le intestazioni della risposta. L’opzione -w “n”/–write-out “n” aggiunge un newline dopo il corpo della risposta.

Vedere qual è lo stato del dispositivo:

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

Inizializzazione #

Un nuovo NetHSM deve essere prima approvvigionato con le passphrase e l’ora corrente. La Admin Passphrase è la passphrase dell”Administrator, che è il super utente del NetHSM. La Passphrase di sblocco è usata per criptare l’archivio di dati riservati del NetHSM.

Nota

L’istanza demo di NetHSM a nethsmdemo.nitrokey.com è già fornita.

$ 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 può essere usato in modalità Attended Boot e Unattended Boot.

In modalità Attended Boot è necessario inserire la Unlock Passphrase durante ogni avvio, che è usata per crittografare l’archivio dati. Per ragioni di sicurezza questa modalità è raccomandata.
Nella modalità Unattended Boot non è richiesta alcuna Passphrase di sblocco, quindi il NetHSM può avviarsi senza sorveglianza e l’archivio dati è memorizzato in modo non criptato. Usa questa modalità se i tuoi requisiti di disponibilità non possono essere soddisfatti con la modalità Attended Boot.

Recupera la modalità corrente:

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

Passare alla modalità Avvio non assistito:

$ 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

Oppure tornare alla modalità Attended Boot:

$ 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

Gestione degli utenti #

Creare un utente #

Ora create un nuovo utente con il ruolo di operatore che può essere usato per firmare e decifrare i dati. Notate che il NetHSM assegna un ID utente casuale se non lo specifichiamo.

$ 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

Gestione delle chiavi #

Il NetHSM supporta le chiavi RSA, ED25519 e ECDSA. Quando si crea una chiave, è necessario selezionare sia l’algoritmo di chiave che i meccanismi di chiave da utilizzare. Le chiavi RSA possono essere usate per la decrittazione (con le modalità raw, PKCS #1 e OAEP con MD5, SHA1, SHA224, SHA256, SHA384 o SHA512) e per la firma (con le modalità PKCS #1 e PSS con MD5, SHA1, SHA224, SHA256, SHA384 o SHA512). Gli altri algoritmi supportano solo il meccanismo di firma.

Per una lista completa di algoritmi e meccanismi di chiavi disponibili, vedere la documentazione API per i tipi KeyAlgorithm e KeyMechanism.

Generare le chiavi #

In questa guida, vogliamo usare una chiave RSA per decifrare i dati usando PKCS #1 e per firmare i dati con PSS usando SHA256. Quindi generiamo una nuova chiave sul NetHSM. Assicuratevi di usare l’algoritmo RSA e di selezionare i meccanismi di chiave RSA_Signature_PSS_SHA256 e RSA_Decryption_PKCS1. Se non si specifica un ID chiave, NetHSM genererà un ID casuale per la nuova chiave.

$ 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

Importazione di chiavi #

Invece di generare una chiave sul NetHSM, potete anche importare chiavi private esistenti nel 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

Chiavi dell’elenco #

Per assicurarsi che la chiave sia stata creata e che abbia le impostazioni corrette dell’algoritmo e del meccanismo, possiamo interrogare tutte le chiavi sul 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"}]

Mostra dettagli chiave #

Possiamo anche interrogare la chiave pubblica della coppia di chiavi generata:

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

Per poter utilizzare la chiave con OpenSSL, la esportiamo come file PEM e la memorizziamo come public.pem:

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

Possiamo ispezionare la chiave con openssl e usarla per la crittografia o la verifica della firma (come descritto nella prossima sezione):

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

Certificati chiave #

È possibile impostare e interrogare i certificati per le chiavi memorizzate su un’istanza di NetHSM:

$ 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

Richieste di firma di certificati chiave #

Il NetHSM supporta la generazione di Certificate Signing Requests (CSR) per le chiavi memorizzate:

$ 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

Operazioni chiave #

Decrittazione #

Possiamo criptare i dati per la chiave memorizzata sul NetHSM usando openssl. (public.pem è il file della chiave pubblica che abbiamo creato nella sezione Show Key Details).

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

Ora possiamo usare il NetHSM per decifrare i dati:

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

Firma #

Allo stesso modo, possiamo firmare i dati usando la chiave sul NetHSM. Per RSA e ECDSA, dobbiamo prima calcolare un digest:

$ echo 'NetHSM rulez!' > data

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

Poi possiamo creare una firma da questo digest usando il 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

Quindi utilizzare OpenSSL per verificare la firma:

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

Verified OK

Backups #

È possibile creare un backup del NetHSM che cattura sia la configurazione che le chiavi memorizzate. Per creare un backup, devi prima impostare una passphrase di backup che viene utilizzata per crittografare il file di backup:

$ 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

Ora dovete creare un utente con il ruolo 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

Ottenere il backup e memorizzarlo in un file:

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

Questo file di backup può essere ripristinato su un’istanza NetHSM non provvista:

$ 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

Aggiornamenti #

Gli aggiornamenti per il NetHSM possono essere installati in un processo in due fasi. Prima devi caricare l’immagine di aggiornamento sul NetHSM. L’immagine viene poi controllata e convalidata. Se la convalida ha successo, le note di rilascio per l’aggiornamento sono restituite dal NetHSM:

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

Se volete continuare con l’installazione, potete ora impegnare l’aggiornamento:

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

In alternativa, è possibile annullare l’aggiornamento:

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