Juurdepääs NetHSMile REST API abil#

See õpetus näitab, kuidas pääseda NetHMSi juurde REST API kaudu. Kasutajaliides on dokumenteeritud kuskil, ja selle spetsifikatsioon on saadaval kui RAML ja kui OpenAPI (Swagger).

Märkus

Kui kasutate NetHSMi demoinstantsi, millel on isesigneeritud sertifikaat, näiteks kasutades Dockeri kujutist, peate kasutama curl’ile valikut –insecure/-k, et jätta sertifikaadi kontroll vahele.

Märkus

Esmalt määrake $NETHSM_HOST väärtuseks NetHSM-i IP-aadress või URL. Meie demoserver on kättesaadav aadressil https://nethsmdemo.nitrokey.com/.

Kõigepealt vaatame, mis meil siin on:

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

Märkus

Valik -i/–include paneb curl’i printima HTTP staatuskoodi ja vastuse päised. Valik -w ‚n‘/–write-out ‚n‘ lisab vastuse kehale uue rea.

Vaadake, milline on seadme olek:

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

Initsialiseerimine#

Uus NetHSM tuleb kõigepealt varustada salasõnade ja praeguse ajaga. Admin Passphrase on Administraatori salasõna, mis on NetHSMi ülemkasutaja. Unlock Passphrase kasutatakse NetHSMi konfidentsiaalse andmehoidla krüpteerimiseks.

Märkus

NetHSMi demoinstants aadressil nethsmdemo.nitrokey.com on juba loodud.

$ 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

NetHSMi saab kasutada Attended Boot režiimis ja Unattended Boot režiimis.

  • Režiimis Attended Boot tuleb iga käivitamise ajal sisestada Unlock Passphrase, mida kasutatakse andmesalvestuse krüpteerimiseks. Turvalisuse huvides on see režiim soovitatav.

  • Režiimil Unattended Boot ei ole lukustamata salasõna vaja, seega võib NetHSM käivituda järelevalveta ja andmesalvestus salvestatakse krüpteerimata. Kasutage seda režiimi, kui teie kättesaadavusnõudeid ei saa täita režiimiga Attended Boot.

Praeguse režiimi väljavõtmine:

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

Lülita ümber Vaheldatud käivitamise režiimile:

$ 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

Või lülitage tagasi režiimi 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

Kasutajate haldamine#

Loo kasutaja#

Nüüd looge uus kasutaja operaatori rolliga, mida saab kasutada andmete allkirjastamiseks ja dekrüpteerimiseks. Pange tähele, et NetHSM määrab juhusliku kasutajatunnuse, kui me seda ei määra.

$ 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

Võtmehaldus#

NetHSM toetab RSA, ED25519 ja ECDSA võtmeid. Võtme loomisel tuleb valida nii võtmealgoritm kui ka kasutatavad võtmemehhanismid. RSA võtmeid saab kasutada dekrüpteerimiseks (režiimidega raw, PKCS#1 ja OAEP koos MD5, SHA1, SHA224, SHA256, SHA384 või SHA512) ja allkirjastamiseks (režiimidega PKCS#1 ja PSS koos MD5, SHA1, SHA224, SHA256, SHA384 või SHA512). Teised algoritmid toetavad ainult allkirjastamise mehhanismi.

Olemasolevate võtmealgoritmide ja võtmemehhanismide täieliku loetelu leiate tüübi KeyAlgorithm ja KeyMechanism API-dokumentatsioonist.

Võtmete genereerimine#

Selles jaotises tahame kasutada RSA-võtit andmete dekrüpteerimiseks PKCS#1 abil ja andmete allkirjastamiseks PSS-iga, kasutades SHA256. Seega genereerime NetHSMis uue võtme. Veenduge, et kasutate RSA algoritmi ja valite võtmemehhanismid RSA_Signature_PSS_SHA256 ja RSA_Decryption_PKCS1. Kui te ei määra võtme ID-d, genereerib NetHSM uue võtme jaoks juhusliku 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

Impordi võtmed#

Selle asemel, et genereerida võti NetHSMis, võite ka olemasolevaid privaatvõtmeid NetHSMi importida:

$ 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

Loetelu võtmed#

Et veenduda, et võti on loodud ja et sellel on õiged algoritmi ja mehhanismi seaded, võime küsida kõiki NetHSMi võtmeid:

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

Näita võtme üksikasju#

Samuti saame küsida genereeritud võtmepaari avalikku võtit:

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

Selleks, et saaksime võtit kasutada OpenSSLiga, ekspordime selle PEM-failina ja salvestame selle public.pem:

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

Me võime OpenSSL-i abil kontrollida võtit ja kasutada seda krüpteerimiseks või allkirja kontrollimiseks (nagu on kirjeldatud järgmises jaotises):

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

Võtmesertifikaadid#

NetHSMi instantsi salvestatud võtmete sertifikaate on võimalik määrata ja pärida:

$ 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

Võtmesertifikaadi allkirjastamise taotlused#

NetHSM toetab salvestatud võtmete jaoks sertifikaadi allkirjastamistaotluste (CSR) genereerimist:

$ 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

Peamised toimingud#

Dekrüpteerimine#

NetHSM-i salvestatud võtme jaoks saame andmeid krüpteerida, kasutades OpenSSL-i. (public.pem on avaliku võtme fail, mille me lõime jaotises Show Key Details).

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

Nüüd saame andmete dekrüpteerimiseks kasutada NetHSMi:

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

Allkirjastamine#

Samamoodi saame andmeid allkirjastada, kasutades NetHSMi võtit. RSA ja ECDSA puhul peame kõigepealt arvutama digesti:

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

Seejärel saame sellest digist luua allkirja, kasutades NetHSM-i:

$ 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

Ja seejärel kasutage OpenSSL-i allkirja kontrollimiseks:

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

Verified OK

Varukoopiaid#

On võimalik luua NetHSMi varukoopia, mis sisaldab nii konfiguratsiooni kui ka salvestatud võtmeid. Varukoopia loomiseks tuleb kõigepealt määrata varukoopia salasõna, mida kasutatakse varukoopiafaili krüpteerimiseks:

$ 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

Nüüd peate looma kasutaja, kellel on R-Backup roll:

$ 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

Hankige varukoopia ja salvestage see faili:

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

Seda varukoopiafaili saab taastada ainult NetHSMi mitteproviseeritud instantsil:

$ 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

Uuendused#

NetHSMi uuendusi saab paigaldada kaheastmelise protsessina. Esmalt tuleb uuenduse kujutis NetHSMi üles laadida. Seejärel kontrollitakse ja kinnitatakse kujutis. Kui valideerimine on edukas, tagastab NetHSM uuenduse väljalaskeandmed:

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

Kui soovite paigaldamist jätkata, saate nüüd uuenduse kinnitada:

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

Teise võimalusena saate uuenduse tühistada:

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