Piekļuve NetHSM, izmantojot REST API#

Šajā pamācībā ir parādīts, kā piekļūt NetHMS, izmantojot REST API. Interfeiss ir dokumentēts šeit, un tā specifikācija ir pieejama kā RAML un kā OpenAPI (Swagger).

Piezīme

Ja izmantojat NetHSM demonstrācijas gadījumu ar pašparakstītu sertifikātu, piemēram, izmantojot Docker attēlu, jums būs jāizmanto –insecure/-k opcija curl, lai izlaistu sertifikāta pārbaudi.

Piezīme

Vispirms iestatiet vērtību $NETHSM_HOST uz NetHSM IP adresi vai URL. Mūsu demo serveri var sasniegt, izmantojot adresi https://nethsmdemo.nitrokey.com/

Vispirms aplūkosim, kas mums šeit ir:

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

Piezīme

Iespēja -i/–include liek curl izdrukāt HTTP statusa kodu un atbildes galvenes. Parametrs -w ‚n‘/–write-out ‚n‘ pievieno jauno rindu aiz atbildes ķermeņa.

Skatiet ierīces statusu:

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

Inicializācija#

Vispirms ir jānodrošina jauns NetHSM ar piekļuves frāzēm un pašreizējo laiku. Admin parole ir Administratora parole, kas ir NetHSM superlietotājs. Atbloķēšanas paroli izmanto, lai šifrētu NetHSM konfidenciālo datu krātuvi.

Piezīme

NetHSM demo instance vietnē nethsmdemo.nitrokey.com jau ir nodrošināta.

$ 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 var izmantot Attended Boot un Unattended Boot režīmā.

  • Attended Boot režīmā katras palaišanas laikā ir jāievada Unlock Passphrase, kas tiek izmantota datu krātuves šifrēšanai. Drošības apsvērumu dēļ šis režīms ir ieteicams.

  • Unattended Boot režīmā nav nepieciešama atbloķēšanas parole, tāpēc NetHSM var sākt darboties bez uzraudzības un datu krātuve tiek saglabāta nešifrētā veidā. Izmantojiet šo režīmu, ja pieejamības prasības nevar izpildīt ar Attended Boot režīmu.

Atgūst pašreizējo režīmu:

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

Pārslēdziet uz Unattended Boot režīmu:

$ 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

Vai arī pārslēdziet atpakaļ uz Attended Boot režīmu:

$ 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

Lietotāju pārvaldība#

Lietotāja izveide#

Tagad izveidojiet jaunu lietotāju ar operatora lomu, kuru var izmantot datu parakstīšanai un atšifrēšanai. Ņemiet vērā, ka NetHSM piešķir nejaušu lietotāja ID, ja mēs to nenorādām.

$ 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

Atslēgas pārvaldība#

NetHSM atbalsta RSA, ED25519 un ECDSA atslēgas. Veidojot atslēgu, ir jāizvēlas gan atslēgas algoritms, gan atslēgas mehānismi, kas tiks izmantoti. RSA atslēgas var izmantot atšifrēšanai (ar režīmiem raw, PKCS#1 un OAEP ar MD5, SHA1, SHA224, SHA256, SHA384 vai SHA512) un parakstīšanai (ar režīmiem PKCS#1 un PSS ar MD5, SHA1, SHA224, SHA256, SHA384 vai SHA512). Pārējie algoritmi atbalsta tikai paraksta mehānismu.

Pilnu pieejamo atslēgu algoritmu un atslēgu mehānismu sarakstu skatiet API dokumentācijā par KeyAlgorithm un KeyMechanism tipiem.

Ģenerēt atslēgas#

Šajā sadaļā mēs vēlamies izmantot RSA atslēgu, lai atšifrētu datus, izmantojot PKCS#1, un parakstītu datus ar PSS, izmantojot SHA256. Tāpēc ģenerēsim jaunu atslēgu NetHSM. Pārliecinieties, ka tiek izmantots RSA algoritms un izvēlēti atslēgas mehānismi RSA_Signature_PSS_SHA256 un RSA_Decryption_PKCS1. Ja nenorādīsiet atslēgas ID, NetHSM jaunajai atslēgai ģenerēs nejaušu ID.

$ 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ēšanas atslēgas#

Tā vietā, lai ģenerētu atslēgu NetHSM, varat arī importēt esošās privātās atslēgas 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

Saraksta atslēgas#

Lai pārliecinātos, ka atslēga ir izveidota un tai ir pareizie algoritma un mehānisma iestatījumi, mēs varam pieprasīt visas NetHSM atslēgas:

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

Rādīt atslēgas informāciju#

Varam arī pieprasīt ģenerētā atslēgu pāra publisko atslēgu:

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

Lai atslēgu varētu izmantot ar OpenSSL, mēs to eksportējam kā PEM failu un saglabājam kā public.pem:

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

Mēs varam pārbaudīt atslēgu ar OpenSSL un izmantot to šifrēšanai vai paraksta pārbaudei (kā aprakstīts nākamajā sadaļā):

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

Atslēgas sertifikāti#

Ir iespējams iestatīt un pieprasīt sertifikātus NetHSM instancē saglabātajām atslēgām:

$ 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

Atslēgas sertifikātu parakstīšanas pieprasījumi#

NetHSM atbalsta sertifikātu parakstīšanas pieprasījumu (CSR) ģenerēšanu saglabātajām atslēgām:

$ 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

Galvenās darbības#

Dešifrēšana#

Mēs varam šifrēt NetHSM saglabātās atslēgas datus, izmantojot OpenSSL. (public.pem ir publiskās atslēgas fails, ko izveidojām sadaļā Show Key Details).)

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

Tagad mēs varam izmantot NetHSM, lai atšifrētu datus:

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

Parakstīšanās#

Līdzīgi mēs varam parakstīt datus, izmantojot NetHSM atslēgu. RSA un ECDSA gadījumā vispirms ir jāaprēķina digest:

$ echo 'NetHSM rulez!' > data
$ openssl dgst -sha256 -binary data | base64 > data.digest

Pēc tam mēs varam izveidot parakstu, izmantojot 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

Un pēc tam paraksta pārbaudei izmantojiet OpenSSL:

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

Verified OK

Rezerves kopijas#

Ir iespējams izveidot NetHSM rezerves kopiju, kas satur gan konfigurāciju, gan saglabātās atslēgas. Lai izveidotu dublējumu, vispirms ir jāiestata dublējuma parole, kas tiek izmantota dublējuma faila šifrēšanai:

$ 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

Tagad ir jāizveido lietotājs ar lomu 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

Iegūstiet dublējumu un saglabājiet to failā:

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

Šo dublējuma failu var atjaunot tikai neievietotā NetHSM instancē:

$ 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

Atjauninājumi#

NetHSM atjauninājumus var instalēt divpakāpju procesā. Vispirms ir jāielādē atjauninājuma attēls uz NetHSM. Pēc tam attēls tiek pārbaudīts un apstiprināts. Ja validācija ir sekmīga, NetHSM atgriež atjauninājuma izlaiduma piezīmes:

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

Ja vēlaties turpināt instalēšanu, tagad varat veikt atjauninājumu:

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

Varat arī atcelt atjaunināšanu:

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