Prieiga prie „NetHSM“ naudojant REST API#

Inicializacija
Naudotojo valdymas
- Sukurti naudotoją
Raktų valdymas
Pagrindinės operacijos
- Dešifravimas
- Pasirašymas
Atsarginės kopijos
Atnaujinimai

Šioje pamokoje parodyta, kaip pasiekti NetHMS per REST API. Sąsaja dokumentuojama čia, o jos specifikaciją galima rasti kaip RAML ir kaip OpenAPI (Swagger).

Pastaba

Jei naudojate NetHSM demonstracinį pavyzdį su savarankiškai pasirašytu sertifikatu, pavyzdžiui, naudodami „Docker“ atvaizdą, norėdami praleisti sertifikato patikrinimą, turėsite naudoti curl parinktį –insecure/-k.

Pastaba

Pirmiausia nustatykite $NETHSM_HOST reikšmę, kad ji būtų lygi jūsų NetHSM IP adresui arba URL. Mūsų demonstracinį serverį galima pasiekti adresu https://nethsmdemo.nitrokey.com/

Pirmiausia pažiūrėkime, ką čia turime:

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

Pastaba

Pasirinktis -i/–include verčia curl spausdinti HTTP būsenos kodą ir atsakymo antraštes. Parinktis -w ‚n‘/–write-out ‚n‘ prideda naują eilutę po atsakymo kūno.

Pažiūrėkite, kokia yra prietaiso būsena:

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

Inicializacija #

Pirmiausia naujam NetHSM reikia suteikti slaptažodžių frazes ir dabartinį laiką. Admin slaptažodis - tai Administrator slaptažodis, kuris yra vyriausiasis NetHSM naudotojas. Slaptažodis Unlock Passphrase naudojamas NetHSM konfidencialių duomenų Storagei užšifruoti.

Pastaba

NetHSM demonstracinė instancija adresu nethsmdemo.nitrokey.com jau sukurta.

$ 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 galima naudoti Attended Boot ir Unattended Boot režimu.

Naudojant Attended Boot režimą, kiekvieno paleidimo metu reikia įvesti Unlock Passphrase, kuri naudojama duomenų Storagei užšifruoti. Saugumo sumetimais rekomenduojama naudoti šį režimą.
Naudojant Neprižiūrimo paleidimo režimą, atrakinimo slaptažodžio nereikia, todėl „NetHSM“ gali būti paleidžiamas be priežiūros, o duomenų Storage saugoma neužšifruota. Šį režimą naudokite, jei jūsų prieinamumo reikalavimų negalima įvykdyti naudojant Attended Boot režimą.

Gauti dabartinį režimą:

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

Perjunkite į Neprižiūrimo įkrovimo režimą:

$ 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

Arba grįžkite į Attended Boot režimą:

$ 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

Naudotojo valdymas #

Sukurti naudotoją #

Dabar sukurkite naują naudotoją su operatoriaus vaidmeniu, kuris gali būti naudojamas duomenims pasirašyti ir iššifruoti. Atkreipkite dėmesį, kad NetHSM priskiria atsitiktinį naudotojo ID, jei jo nenurodome.

$ 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

Raktų valdymas #

NetHSM palaiko RSA, ED25519 ir ECDSA raktus. Kurdami raktą, turite pasirinkti ir rakto algoritmą, ir naudojamus rakto mechanizmus. RSA raktai gali būti naudojami dešifravimui (su režimais raw, PKCS#1 ir OAEP su MD5, SHA1, SHA224, SHA256, SHA384 arba SHA512) ir pasirašymui (su režimais PKCS#1 ir PSS su MD5, SHA1, SHA224, SHA256, SHA384 arba SHA512). Kiti algoritmai palaiko tik parašo mechanizmą.

Išsamų galimų raktų algoritmų ir raktų mechanizmų sąrašą rasite API dokumentuose, skirtuose KeyAlgorithm ir KeyMechanism tipams.

Generuoti raktus #

Šiame skyriuje norime naudoti RSA raktą duomenims iššifruoti, naudodami PKCS#1, ir duomenims pasirašyti su PSS, naudodami SHA256. Taigi sukurkime naują raktą NetHSM. Įsitikinkite, kad naudojate RSA algoritmą ir pasirinkote RSA_Signature_PSS_SHA256 ir RSA_Decryption_PKCS1 raktų mechanizmus. Jei nenurodysite rakto ID, „NetHSM“ sugeneruos atsitiktinį naujojo rakto 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

Importo raktai #

Užuot generavę raktą „NetHSM“, taip pat galite importuoti esamus privačius raktus į „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

Sąrašo raktai #

Norėdami įsitikinti, ar raktas sukurtas ir ar jame nustatyti teisingi algoritmo ir mechanizmo nustatymai, galime pateikti užklausą visiems NetHSM raktams:

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

Rodyti informaciją apie raktą #

Taip pat galime pateikti užklausą apie sukurtos raktų poros viešąjį raktą:

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

Kad raktą galėtume naudoti su OpenSSL, eksportuojame jį kaip PEM failą ir saugome kaip public.pem:

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

Raktą galime patikrinti su „OpenSSL“ ir naudoti šifravimui arba parašo tikrinimui (kaip aprašyta kitame skyriuje):

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

Pagrindiniai sertifikatai #

Galima nustatyti ir užklausti NetHSM egzemplioriuje saugomų raktų sertifikatus:

$ 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

Rakto sertifikato pasirašymo užklausos #

NetHSM palaiko saugomų raktų sertifikatų pasirašymo prašymų (CSR) generavimą:

$ 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

Pagrindinės operacijos #

Dešifravimas #

Naudodami OpenSSL galime užšifruoti duomenis, skirtus NetHSM saugomam raktui. (public.pem yra viešojo rakto failas, kurį sukūrėme Show Key Details skirsnyje.)

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

Dabar galime naudoti NetHSM duomenims iššifruoti:

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

Pasirašymas #

Panašiai galime pasirašyti duomenis naudodami NetHSM raktą. RSA ir ECDSA atveju pirmiausia turime apskaičiuoti suvestinę:

$ echo 'NetHSM rulez!' > data

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

Tada iš šios suvestinės, naudodami NetHSM, galime sukurti parašą:

$ 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

Tada naudokite „OpenSSL“ parašui patikrinti:

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

Verified OK

Atsarginės kopijos #

Galima sukurti atsarginę „NetHSM“ kopiją, kurioje būtų ir konfigūracija, ir išsaugoti raktai. Norėdami sukurti atsarginę kopiją, pirmiausia turite nustatyti atsarginės kopijos slaptažodį, kuris naudojamas atsarginės kopijos failui užšifruoti:

$ 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

Dabar turite sukurti naudotoją, kuriam suteiktas R-Backup vaidmuo:

$ 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

Gaukite atsarginę kopiją ir išsaugokite ją faile:

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

Šį atsarginės kopijos failą galima atkurti tik neįdiegtoje NetHSM instancijoje:

$ 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

Atnaujinimai #

NetHSM atnaujinimus galima įdiegti dviem etapais. Pirmiausia reikia įkelti atnaujinimo atvaizdą į „NetHSM“. Tada atvaizdas patikrinamas ir patvirtinamas. Jei patvirtinimas sėkmingas, „NetHSM“ grąžina atnaujinimo išleidimo pastabas:

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

Jei norite tęsti diegimą, dabar galite patvirtinti naujinimą:

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

Taip pat galite atšaukti naujinimą:

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