Πρόσβαση σε ένα NetHSM χρησιμοποιώντας το REST API#

Αυτό το σεμινάριο παρουσιάζει τον τρόπο πρόσβασης στο NetHMS μέσω του API REST. Η διεπαφή τεκμηριώνεται εδώ, και οι προδιαγραφές της είναι διαθέσιμες ως RAML και ως OpenAPI (Swagger).

Σημείωση

Εάν χρησιμοποιείτε μια demo περίπτωση NetHSM με αυτο-υπογεγραμμένο πιστοποιητικό, για παράδειγμα χρησιμοποιώντας την εικόνα Docker, θα πρέπει να χρησιμοποιήσετε την επιλογή –insecure/-k για την curl για να παραλείψετε τον έλεγχο του πιστοποιητικού.

Σημείωση

Πρώτα ορίστε την τιμή του $NETHSM_HOST στη διεύθυνση IP ή τη διεύθυνση URL του NetHSM σας. Ο διακομιστής επίδειξης είναι προσβάσιμος στη διεύθυνση https://nethsmdemo.nitrokey.com/.

Πρώτον, ας δούμε τι έχουμε εδώ:

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

Σημείωση

Η επιλογή -i/–include αναγκάζει την curl να εκτυπώσει τον κωδικό κατάστασης HTTP και τις επικεφαλίδες απόκρισης. Η επιλογή -w “n”/–write-out “n” προσθέτει μια νέα γραμμή μετά το σώμα της απάντησης.

Δείτε ποια είναι η κατάσταση της συσκευής:

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

Αρχικοποίηση#

Ένα νέο NetHSM πρέπει πρώτα να εφοδιαστεί με κωδικούς πρόσβασης και την τρέχουσα ώρα. Η Διαχειριστική φράση πρόσβασης είναι η φράση πρόσβασης του Διαχειριστή, ο οποίος είναι ο υπερ-χρήστης του NetHSM. Η Unlock Passphrase χρησιμοποιείται για την κρυπτογράφηση του χώρου αποθήκευσης εμπιστευτικών δεδομένων του NetHSM.

Σημείωση

Η παρουσία επίδειξης NetHSM στη διεύθυνση nethsmdemo.nitrokey.com είναι ήδη εφοδιασμένη.

$ 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 μπορεί να χρησιμοποιηθεί σε λειτουργία Αυτόνομης εκκίνησης και Αυτόνομης εκκίνησης.

  • Στη λειτουργία Attended Boot, η Unlock Passphrase πρέπει να εισάγεται κατά τη διάρκεια κάθε εκκίνησης, η οποία χρησιμοποιείται για την κρυπτογράφηση του χώρου αποθήκευσης δεδομένων. Για λόγους ασφαλείας, συνιστάται αυτή η λειτουργία.

  • Στη λειτουργία Ανεπίβλεπτη εκκίνηση δεν απαιτείται η φράση πρόσβασης ξεκλειδώματος, επομένως το NetHSM μπορεί να ξεκινήσει χωρίς επιτήρηση και η αποθήκευση δεδομένων αποθηκεύεται χωρίς κρυπτογράφηση. Χρησιμοποιήστε αυτή τη λειτουργία εάν οι απαιτήσεις σας για διαθεσιμότητα δεν μπορούν να ικανοποιηθούν με τη λειτουργία Αυτόνομης εκκίνησης.

Ανάκτηση της τρέχουσας λειτουργίας:

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

Μεταβείτε στη λειτουργία Ανεπίβλεπτης εκκίνησης:

$ 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

Ή γυρίστε πίσω στη λειτουργία 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

Διαχείριση χρηστών#

Δημιουργία χρήστη#

Τώρα δημιουργήστε έναν νέο χρήστη με ρόλο χειριστή που μπορεί να χρησιμοποιηθεί για την υπογραφή και αποκρυπτογράφηση δεδομένων. Σημειώστε ότι το NetHSM εκχωρεί ένα τυχαίο αναγνωριστικό χρήστη αν δεν το καθορίσουμε.

$ 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

Διαχείριση κλειδιών#

Το NetHSM υποστηρίζει κλειδιά RSA, ED25519 και ECDSA. Κατά τη δημιουργία ενός κλειδιού, πρέπει να επιλέξετε τόσο τον αλγόριθμο κλειδιού όσο και τους μηχανισμούς κλειδιού που θα χρησιμοποιήσετε. Τα κλειδιά RSA μπορούν να χρησιμοποιηθούν για αποκρυπτογράφηση (με τους τρόπους raw, PKCS#1 και OAEP με MD5, SHA1, SHA224, SHA256, SHA384 ή SHA512) και για υπογραφές (με τους τρόπους PKCS#1 και PSS με MD5, SHA1, SHA224, SHA256, SHA384 ή SHA512). Οι άλλοι αλγόριθμοι υποστηρίζουν μόνο τον μηχανισμό υπογραφής.

Για έναν πλήρη κατάλογο των διαθέσιμων αλγορίθμων και μηχανισμών κλειδιών, ανατρέξτε στην τεκμηρίωση API για τους τύπους KeyAlgorithm και KeyMechanism.

Δημιουργία κλειδιών#

Σε αυτή την ενότητα, θέλουμε να χρησιμοποιήσουμε ένα κλειδί RSA για την αποκρυπτογράφηση δεδομένων χρησιμοποιώντας PKCS#1 και για την υπογραφή δεδομένων με PSS χρησιμοποιώντας SHA256. Ας δημιουργήσουμε λοιπόν ένα νέο κλειδί στο NetHSM. Βεβαιωθείτε ότι χρησιμοποιείτε τον αλγόριθμο RSA και ότι επιλέγετε τους μηχανισμούς κλειδιών RSA_Signature_PSS_SHA256 και RSA_Decryption_PKCS1. Εάν δεν καθορίσετε αναγνωριστικό κλειδιού, το NetHSM θα δημιουργήσει ένα τυχαίο αναγνωριστικό για το νέο κλειδί.

$ 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

Εισαγωγή κλειδιών#

Αντί να δημιουργήσετε ένα κλειδί στο NetHSM, μπορείτε επίσης να εισαγάγετε υπάρχοντα ιδιωτικά κλειδιά στο 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

Λίστα κλειδιών#

Για να βεβαιωθούμε ότι το κλειδί έχει δημιουργηθεί και έχει τις σωστές ρυθμίσεις αλγορίθμου και μηχανισμού, μπορούμε να ζητήσουμε όλα τα κλειδιά στο 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"}]

Εμφάνιση λεπτομερειών κλειδιού#

Μπορούμε επίσης να ζητήσουμε το δημόσιο κλειδί του παραγόμενου ζεύγους κλειδιών:

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

Για να μπορέσουμε να χρησιμοποιήσουμε το κλειδί με το OpenSSL, το εξάγουμε ως αρχείο PEM και το αποθηκεύουμε ως public.pem:

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

Μπορούμε να επιθεωρήσουμε το κλειδί με το OpenSSL και να το χρησιμοποιήσουμε για κρυπτογράφηση ή επαλήθευση υπογραφής (όπως περιγράφεται στην επόμενη ενότητα):

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

Πιστοποιητικά κλειδιών#

Είναι δυνατή η ρύθμιση και η αναζήτηση πιστοποιητικών για τα κλειδιά που είναι αποθηκευμένα σε μια περίπτωση 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

Αιτήματα υπογραφής πιστοποιητικού κλειδιού#

Το NetHSM υποστηρίζει τη δημιουργία αιτήσεων υπογραφής πιστοποιητικών (CSR) για τα αποθηκευμένα κλειδιά:

$ 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

Βασικές λειτουργίες#

Αποκρυπτογράφηση#

Μπορούμε να κρυπτογραφήσουμε δεδομένα για το κλειδί που είναι αποθηκευμένο στο NetHSM χρησιμοποιώντας το OpenSSL. (Το public.pem είναι το αρχείο του δημόσιου κλειδιού που δημιουργήσαμε στην ενότητα Show Key Details).

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

Τώρα μπορούμε να χρησιμοποιήσουμε το NetHSM για να αποκρυπτογραφήσουμε τα δεδομένα:

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

Υπογραφή#

Ομοίως, μπορούμε να υπογράψουμε δεδομένα χρησιμοποιώντας το κλειδί στο NetHSM. Για RSA και ECDSA, πρέπει πρώτα να υπολογίσουμε μια σύνοψη:

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

Στη συνέχεια, μπορούμε να δημιουργήσουμε μια υπογραφή από αυτό το digest χρησιμοποιώντας το 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

Και στη συνέχεια χρησιμοποιήστε το OpenSSL για να επαληθεύσετε την υπογραφή:

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

Verified OK

Αντίγραφα ασφαλείας#

Είναι δυνατή η δημιουργία αντιγράφου ασφαλείας του NetHSM που περιέχει τόσο τη διαμόρφωση όσο και τα αποθηκευμένα κλειδιά. Για να δημιουργήσετε ένα αντίγραφο ασφαλείας, πρέπει πρώτα να ορίσετε μια φράση πρόσβασης για το αντίγραφο ασφαλείας, η οποία χρησιμοποιείται για την κρυπτογράφηση του αρχείου αντιγράφου ασφαλείας:

$ 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

Τώρα πρέπει να δημιουργήσετε έναν χρήστη με τον ρόλο 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

Πάρτε το αντίγραφο ασφαλείας και αποθηκεύστε το σε ένα αρχείο:

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

Αυτό το αρχείο αντιγράφων ασφαλείας μπορεί να αποκατασταθεί μόνο σε μια μη προβεβλημένη περίπτωση NetHSM:

$ 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

Ενημερώσεις#

Οι ενημερώσεις για το NetHSM μπορούν να εγκατασταθούν με μια διαδικασία δύο βημάτων. Πρώτα πρέπει να μεταφορτώσετε την εικόνα ενημέρωσης στο NetHSM. Στη συνέχεια, η εικόνα ελέγχεται και επικυρώνεται. Εάν η επικύρωση είναι επιτυχής, το NetHSM επιστρέφει τις σημειώσεις έκδοσης για την ενημέρωση:

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

Αν θέλετε να συνεχίσετε την εγκατάσταση, μπορείτε τώρα να δεσμεύσετε την ενημέρωση:

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

Εναλλακτικά, μπορείτε να ακυρώσετε την ενημέρωση:

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