NetHSM elérése a REST API használatával#

Inicializálás
Felhasználó kezelése
- Felhasználó létrehozása
Kulcskezelés
Kulcsműveletek
- Dekódolás
- Aláírás
Biztonsági mentések
Frissítések

Ez a bemutató azt mutatja be, hogyan lehet a NetHMS-t REST API-n keresztül elérni. Az interfész dokumentációja itt található, és a specifikációja elérhető RAML és OpenAPI (Swagger) formátumban.

Megjegyzés

Ha önaláírt tanúsítvánnyal rendelkező NetHSM demópéldányt használ, például a Docker-kép használatával, akkor a curl-hez a –insecure/-k kapcsolót kell használnia a tanúsítvány ellenőrzésének kihagyásához.

Megjegyzés

Először állítsa be a $NETHSM_HOST értékét a NetHSM IP-címére vagy URL címére. A mi demó szerverünk a https://nethsmdemo.nitrokey.com/ címen érhető el.

Először is nézzük meg, hogy mi van itt:

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

Megjegyzés

A -i/–include opció hatására a curl kiírja a HTTP státuszkódot és a válasz fejléceket. A -w «n»/–write-out «n» opció újsorral egészíti ki a válasz testét.

Nézze meg, hogy mi az eszköz állapota:

$ 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álás #

Az új NetHSM-et először jelszavakkal és az aktuális idővel kell ellátni. Az Admin Passphrase a Administrator jelszava, amely a NetHSM szuperfelhasználója. A Unlock Passphrase a NetHSM bizalmas adattárolójának titkosítására szolgál.

Megjegyzés

A nethsmdemo.nitrokey.com címen található NetHSM demópéldány már készen áll.

$ 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

A NetHSM használható Vigyázott indítás és Vigyázatlan indítás üzemmódban.

Az Attended Boot módban minden indításkor meg kell adni a Unlock Passphrase jelszót, amely az adattároló titkosítására szolgál. Biztonsági okokból ez az üzemmód ajánlott.
A Felügyelet nélküli indítás módban nincs szükség a Feloldási jelszóra, ezért a NetHSM felügyelet nélkül is elindulhat, és az adattároló titkosítatlanul tárolódik. Ezt az üzemmódot akkor használja, ha a rendelkezésre állási követelményei nem teljesíthetők a Védett indítás üzemmóddal.

Az aktuális üzemmód lekérdezése:

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

Váltson Vigyázatlan indítás üzemmódra:

$ 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

Vagy váltson vissza Attended Boot üzemmódba:

$ 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

Felhasználó kezelése #

Felhasználó létrehozása #

Most hozzon létre egy új felhasználót operátor szerepkörrel, amely az adatok aláírására és visszafejtésére használható. Vegye figyelembe, hogy a NetHSM véletlenszerű felhasználói azonosítót rendel hozzá, ha nem adjuk meg.

$ 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

Kulcskezelés #

A NetHSM támogatja az RSA, ED25519 és ECDSA kulcsokat. A kulcs létrehozásakor ki kell választania a kulcsalgoritmust és a használni kívánt kulcsmechanizmust is. Az RSA kulcsok használhatók visszafejtéshez (nyers, PKCS#1 és OAEP módban MD5, SHA1, SHA224, SHA256, SHA384 vagy SHA512-vel) és aláírásokhoz (PKCS#1 és PSS módban MD5, SHA1, SHA224, SHA256, SHA384 vagy SHA512-vel). A többi algoritmus csak az aláírási mechanizmust támogatja.

A rendelkezésre álló kulcsalgoritmusok és kulcsmechanizmusok teljes listáját a KeyAlgorithm és KeyMechanism típusok API-dokumentációjában találja.

Kulcsok generálása #

Ebben a szakaszban egy RSA kulcsot szeretnénk használni az adatok visszafejtésére a PKCS#1 használatával, és az adatok aláírására a PSS segítségével az SHA256 használatával. Generáljunk tehát egy új kulcsot a NetHSM-en. Ügyeljen arra, hogy az RSA algoritmust használja, és válassza az RSA_Signature_PSS_SHA256 és az RSA_Decryption_PKCS1 kulcsmechanizmusokat. Ha nem ad meg kulcsazonosítót, a NetHSM véletlenszerű azonosítót generál az új kulcshoz.

$ 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

Kulcsok importálása #

Ahelyett, hogy a NetHSM-en generálna egy kulcsot, meglévő magánkulcsokat is importálhat a NetHSM-be:

$ 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

Kulcsok listája #

Hogy megbizonyosodjunk arról, hogy a kulcsot létrehoztuk-e, és rendelkezik-e a megfelelő algoritmus- és mechanizmusbeállításokkal, lekérdezhetjük az összes kulcsot a NetHSM-en:

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

Kulcs részletek megjelenítése #

A generált kulcspár nyilvános kulcsát is lekérdezhetjük:

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

Ahhoz, hogy a kulcsot az OpenSSL-lel használhassuk, PEM fájlként exportáljuk és public.pem néven tároljuk:

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

A kulcsot az OpenSSL segítségével megvizsgálhatjuk, és felhasználhatjuk titkosításra vagy aláírás-ellenőrzésre (a következő szakaszban leírtak szerint):

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

Kulcsfontosságú tanúsítványok #

Lehetőség van a NetHSM-példányon tárolt kulcsokhoz tanúsítványok beállítására és lekérdezésére:

$ 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

Kulcs-tanúsítvány aláírási kérelmek #

A NetHSM támogatja a tárolt kulcsok tanúsítványaláírási kérelmeinek (CSR) létrehozását:

$ 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

Kulcsműveletek #

Dekódolás #

A NetHSM-en tárolt kulcs adatait az OpenSSL segítségével titkosíthatjuk. (A public.pem a nyilvános kulcsfájl, amelyet a Kulcs adatainak megjelenítése szakaszban hoztunk létre.)

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

Most már használhatjuk a NetHSM-et az adatok visszafejtéséhez:

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

Aláírás #

Hasonlóképpen aláírhatjuk az adatokat a NetHSM-en lévő kulcs segítségével. Az RSA és az ECDSA esetében először ki kell számolnunk egy kivonatot:

$ echo 'NetHSM rulez!' > data

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

Ezután a NetHSM segítségével létrehozhatunk egy aláírást ebből a kivonatból:

$ 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

Ezután az OpenSSL segítségével ellenőrizze az aláírást:

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

Verified OK

Biztonsági mentések #

Lehetőség van a NetHSM biztonsági másolatának elkészítésére, amely tartalmazza a konfigurációt és a tárolt kulcsokat is. A biztonsági mentés létrehozásához először be kell állítania egy biztonsági mentési jelszót, amely a biztonsági mentési fájl titkosítására szolgál:

$ 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

Most létre kell hoznod egy felhasználót az R-Backup szerepkörrel:

$ 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

Szerezze be a biztonsági másolatot, és tárolja egy fájlban:

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

Ez a biztonsági mentési fájl csak egy nem provizorizált NetHSM-példányon állítható vissza:

$ 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

Frissítések #

A NetHSM frissítései kétlépcsős eljárással telepíthetők. Először fel kell töltenie a frissítési képet a NetHSM-re. Ezt követően a képet ellenőrzik és érvényesítik. Ha az érvényesítés sikeres, a NetHSM visszaküldi a frissítéshez tartozó kiadási megjegyzéseket:

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

Ha folytatni szeretné a telepítést, akkor most már rögzítheti a frissítést:

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

Alternatív megoldásként törölheti a frissítést:

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