Operacja#
Ten rozdział opisuje zadania operacyjne dla użytkowników z rolą Administrator i Operator. Proszę zapoznać się z rozdziałem Role, aby dowiedzieć się więcej o roli.
Ważne
Upewnij się, że przeczytałeś informacje zawarte na początku ` tego dokumentu <index.html>`__ przed rozpoczęciem pracy.
Zarządzanie kluczami#
Wygeneruj klucz#
NetHSM może generować pary kluczy. Zaleca się podanie opcji key ID, aby nadać mu wyrazistą nazwę.
Obsługiwane typy kluczy i odpowiadające im mechanizmy są następujące.
Typ klucza |
Mechanizmy |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Klucze są przypisane do `Namespace <administration.html#namespaces>`__ użytkownika, który generuje klucz.
Klucz można wygenerować w następujący sposób.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Administrator.
Wymagane opcje.
Opcja |
Opis |
---|---|
|
Typ dla wygenerowanego klucza. Możliwe wartości dla argumentu |
|
Mechanizmy dla wygenerowanego klucza. Możliwe wartości dla argumentu |
|
Długość wygenerowanego klucza |
Opcje dodatkowe.
Opcja |
Opis |
---|---|
|
Identyfikator wygenerowanego klucza |
Przykład
$ nitropy nethsm --host $NETHSM_HOST generate-key --type RSA --mechanism RSA_Signature_PSS_SHA256 --mechanism RSA_Decryption_PKCS1 --length 2048 --key-id myFirstKey
Key myFirstKey generated on NetHSM localhost:8443
Informacje na temat punktu końcowego /keys/generate można znaleźć w dokumentacji API.
Klucz importowy#
NetHSM może importować istniejące klucze prywatne do Key Store.
Obsługiwane typy kluczy i odpowiadające im mechanizmy są następujące.
Typ klucza |
Mechanizmy |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Klucze są przypisane do *Namespace* użytkownika, który importuje klucz.
Import można zainicjować w następujący sposób.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Administrator.
Wymagane opcje.
Opcja |
Opis |
---|---|
|
Typ dla wygenerowanego klucza. Możliwe wartości dla argumentu |
|
Mechanizmy dla wygenerowanego klucza. Możliwe wartości dla argumentu |
|
Liczba pierwsza p dla kluczy RSA, zakodowana w base64 |
|
Pierwszy q dla kluczy RSA, zakodowany w base64 |
|
Publiczny wykładnik dla kluczy RSA, zakodowany w base64 |
|
Dane klucza dla kluczy ED25519 lub ECDSA_*, zakodowane w base64 |
Opcje dodatkowe.
Opcja |
Opis |
---|---|
|
ID nowego klucza |
|
Tag dla nowego klucza |
Przykład
$ nitropy nethsm --host $NETHSM_HOST add-key \
--type RSA \
--mechanism RSA_Signature_PSS_SHA256 \
--mechanism RSA_Decryption_PKCS1 \
--key-id myFirstKey \
--public-exponent AQAB \
--prime-p "AOnWFZ+JrI/xOXJU04uYCZOiPVUWd6CSbVseEYrYQYxc7dVroePshz29tc+VEOUP5T0O8lXMEkjFAwjW6C9QTAsPyl6jwyOQluMRIkdN4/7BAg3HAMuGd7VmkGyYrnZWW54sLWp1JD6XJG33kF+9OSar9ETPoVyBgK5punfiUFEL" \
--prime-q "ANT1kWDdP9hZoFKT49dwdM/S+3ZDnxQa7kZk9p+JKU5RaU9e8pS2GOJljHwkES1FH6CUGeIaUi81tRKe2XZhe/163sEyMcxkaaRbBbTc1v6ZDKILFKKt4eX7LAQfhL/iFlgi6pcyUM8QDrm1QeFgGz11ChM0JuQw1WwkX06lg8iv"
Key myFirstKey added to NetHSM localhost:8443
Informacje na temat punktu końcowego /keys można znaleźć w dokumentacji API.
Usuń klawisz#
NetHSM może usuwać klucze z Key Store. Użytkownicy mogą usuwać klucze tylko w swojej przestrzeni *Namespace*.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Administrator.
Argumenty
Argument |
Opis |
---|---|
|
ID klucza, który ma zostać usunięty |
Przykład
$ nitropy nethsm --host $NETHSM_HOST delete-key myFirstKey
Key myFirstKey deleted on NetHSM localhost:8443
Informacje na temat punktu końcowego /keys/{KeyID} można znaleźć w dokumentacji API.
Lista kluczy#
NetHSM może wyświetlić listę wszystkich kluczy w Key Store, które znajdują się w *Namespace* bieżącego użytkownika.
Listę można odzyskać w następujący sposób.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Administrator lub Operator.
Opcje dodatkowe.
Opcja |
Opis |
---|---|
|
Znacznik, który należy wyszukać |
Przykład
$ nitropy nethsm --host $NETHSM_HOST list-keys
Keys on NetHSM localhost:8443:
Key ID Type Mechanisms Operations Tags
----------- ---- ---------------------------------------------- ---------- ----
myFirstKey RSA RSA_Decryption_PKCS1, RSA_Signature_PSS_SHA256 0
Informacje na temat punktu końcowego /keys można znaleźć w dokumentacji API.
Pokaż szczegóły klucza#
NetHSM może wyświetlać bardziej szczegółowe informacje o przechowywanym kluczu. Użytkownicy mogą uzyskać dostęp tylko do kluczy w ich *Namespace*.
Szczegółowe informacje można pobrać w następujący sposób.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Administrator lub Operator.
Przykład
$ nitropy nethsm --host $NETHSM_HOST get-key myFirstKey
Key myFirstKey on NetHSM localhost:8443:
Type: RSA
Mechanisms: RSA_Decryption_RAW
Operations: 0
Modulus: r62XHPWMDdEf2I1WEpSxGowY/fQF8lMPtv3EUQJE/PLWBvehF8G0QY3AVVZ3etlQWiKreOuGDx4Nr2PFNYAu5f+JP2Jc1lsFNOYF8D82RF41MBySbQR+k+44N/04B0ahTBCxX+ovFH7Sd6SzvxMPa7EKvhaOsLbgyrPlFZxQnhIEqJRCSo5DRRD+CRCPpGXsVXgFbJrNilh21i8OZCct4nC2OS191MeDKmCH4tjrfLMwOKJE8zKlwhdtA1uMY49+JuaC48GUFsLYwbLp1723Uv1PjZjC5jbUhScD0u9I+iNrqznAeka4dWsJ9jgA+h6hblSgCs0I3MWOsMXx/Y5PGQ==
Public exponent: AQAB
Informacje na temat punktu końcowego /keys/{KeyID} można znaleźć w dokumentacji API.
Klucz publiczny klucza można pobrać w następujący sposób. Jest on w formacie PKCS#8.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Administrator lub Operator.
Przykład
$ nitropy nethsm --host $NETHSM_HOST get-key myFirstKey --public-key
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr62XHPWMDdEf2I1WEpSx
GowY/fQF8lMPtv3EUQJE/PLWBvehF8G0QY3AVVZ3etlQWiKreOuGDx4Nr2PFNYAu
5f+JP2Jc1lsFNOYF8D82RF41MBySbQR+k+44N/04B0ahTBCxX+ovFH7Sd6SzvxMP
a7EKvhaOsLbgyrPlFZxQnhIEqJRCSo5DRRD+CRCPpGXsVXgFbJrNilh21i8OZCct
4nC2OS191MeDKmCH4tjrfLMwOKJE8zKlwhdtA1uMY49+JuaC48GUFsLYwbLp1723
Uv1PjZjC5jbUhScD0u9I+iNrqznAeka4dWsJ9jgA+h6hblSgCs0I3MWOsMXx/Y5P
GQIDAQAB
-----END PUBLIC KEY-----
Informacje na temat punktu końcowego /keys/{KeyID}/public.pem można znaleźć w dokumentacji API.
Klucz publiczny można sprawdzić na przykład za pomocą OpenSSL w następujący sposób.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Administrator lub Operator.
Przykład
nitropy nethsm --host= $NETHSM_HOST get-key myFirstKey --public-key | openssl rsa -pubin -text
Public-Key: (2048 bit)
Modulus:
00:af:ad:97:1c:f5:8c:0d:d1:1f:d8:8d:56:12:94:
b1:1a:8c:18:fd:f4:05:f2:53:0f:b6:fd:c4:51:02:
44:fc:f2:d6:06:f7:a1:17:c1:b4:41:8d:c0:55:56:
77:7a:d9:50:5a:22:ab:78:eb:86:0f:1e:0d:af:63:
c5:35:80:2e:e5:ff:89:3f:62:5c:d6:5b:05:34:e6:
05:f0:3f:36:44:5e:35:30:1c:92:6d:04:7e:93:ee:
38:37:fd:38:07:46:a1:4c:10:b1:5f:ea:2f:14:7e:
d2:77:a4:b3:bf:13:0f:6b:b1:0a:be:16:8e:b0:b6:
e0:ca:b3:e5:15:9c:50:9e:12:04:a8:94:42:4a:8e:
43:45:10:fe:09:10:8f:a4:65:ec:55:78:05:6c:9a:
cd:8a:58:76:d6:2f:0e:64:27:2d:e2:70:b6:39:2d:
7d:d4:c7:83:2a:60:87:e2:d8:eb:7c:b3:30:38:a2:
44:f3:32:a5:c2:17:6d:03:5b:8c:63:8f:7e:26:e6:
82:e3:c1:94:16:c2:d8:c1:b2:e9:d7:bd:b7:52:fd:
4f:8d:98:c2:e6:36:d4:85:27:03:d2:ef:48:fa:23:
6b:ab:39:c0:7a:46:b8:75:6b:09:f6:38:00:fa:1e:
a1:6e:54:a0:0a:cd:08:dc:c5:8e:b0:c5:f1:fd:8e:
4f:19
Exponent: 65537 (0x10001)
writing RSA key
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr62XHPWMDdEf2I1WEpSx
GowY/fQF8lMPtv3EUQJE/PLWBvehF8G0QY3AVVZ3etlQWiKreOuGDx4Nr2PFNYAu
5f+JP2Jc1lsFNOYF8D82RF41MBySbQR+k+44N/04B0ahTBCxX+ovFH7Sd6SzvxMP
a7EKvhaOsLbgyrPlFZxQnhIEqJRCSo5DRRD+CRCPpGXsVXgFbJrNilh21i8OZCct
4nC2OS191MeDKmCH4tjrfLMwOKJE8zKlwhdtA1uMY49+JuaC48GUFsLYwbLp1723
Uv1PjZjC5jbUhScD0u9I+iNrqznAeka4dWsJ9jgA+h6hblSgCs0I3MWOsMXx/Y5P
GQIDAQAB
-----END PUBLIC KEY-----
Informacje na temat punktu końcowego /keys/{KeyID}/public.pem można znaleźć w dokumentacji API.
Kluczowe certyfikaty#
Możliwe jest ustawianie i odpytywanie certyfikatów dla kluczy przechowywanych w urządzeniu NetHSM.
Obsługiwane typy MIME są następujące.
application/x-pem-file
application/x-x509-ca-cert
application/pgp-keys
Certyfikat można ustawić w następujący sposób.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Administrator.
Wymagane opcje.
Opcja |
Opis |
---|---|
|
ID klucza, dla którego ma być ustawiony certyfikat |
Opcje dodatkowe.
Opcja |
Opis |
---|---|
|
Typ MIME certyfikatu. Dostępne typy MIME są wymienione powyżej. |
Argumenty
Argument |
Opis |
---|---|
|
Plik z certyfikatami |
Przykład
$ nitropy nethsm --host $NETHSM_HOST set-certificate --key-id myFirstKey --mime-type application/x-pem-file /tmp/cert.pem
Updated the certificate for key myFirstKey on NetHSM localhost:8443
Informacje na temat punktu końcowego /keys/{KeyID}/cert można znaleźć w dokumentacji API.
Certyfikat można odzyskać w następujący sposób.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Administrator lub Operator.
Wymagane opcje.
Opcja |
Opis |
---|---|
|
Identyfikator klucza, dla którego chcemy uzyskać certyfikat |
Przykład
$ nitropy nethsm --host $NETHSM_HOST get-certificate --key-id myFirstKey
-----BEGIN CERTIFICATE-----
MIICeTCCAWECFCbuzdkAvc3Zx3W53IoSnmhUen42MA0GCSqGSIb3DQEBCwUAMHsx
CzAJBgNVBAYTAkRFMQ8wDQYDVQQIDAZCZXJsaW4xDzANBgNVBAcMBkJlcmxpbjER
MA8GA1UECgwITml0cm9rZXkxFTATBgNVBAMMDG5pdHJva2V5LmNvbTEgMB4GCSqG
SIb3DQEJARYRaW5mb0BuaXRyb2tleS5jb20wHhcNMjIwODMwMjAxMzA2WhcNMjMw
ODMwMjAxMzA2WjBxMW8wCQYDVQQGEwJERTANBgNVBAcMBkJlcmxpbjANBgNVBAgM
BkJlcmxpbjAPBgNVBAoMCE5pdHJva2V5MBMGA1UEAwwMbml0cm9rZXkuY29tMB4G
CSqGSIb3DQEJARYRaW5mb0BuaXRyb2tleS5jb20wKjAFBgMrZXADIQDc58LGDY9B
wbJFdXTiDalNXrDC60Sxu3eHcpnh1MSoCjANBgkqhkiG9w0BAQsFAAOCAQEAGip8
aU5nJnzm3eic3t1ihUA3VJ0mAPyfrb1Rn8tEKOZo3vg0jpRd9CSESlBsKqhvxsdQ
A3eomM+W7R37TL5+ISm5QrbijLHz3OHoPM68c1Krz3bXTkJetf4YAxpLOPYfXXHv
weRzwVJb4y3E0lJGhZxI3sUE8Yn/T1UvTbu/o/O5P/XTA8vfFrSNQkQxWBgYh4gC
KjFFALqUPFrctSFIi34aqpdihNJWnjSS2Y7INm3oxwkR3NMKP8x4wBGfZK22nHnu
PPzXuMGJTmQM8GHTzltNvLx5Iv2sXoSHClXSpdIT5IBIcR1GmZ78fmcr75OAU0+z
3XbJq/1ij3tKsjV6WA==
-----END CERTIFICATE-----
Informacje na temat punktu końcowego /keys/{KeyID}/cert można znaleźć w dokumentacji API.
Żądania podpisania certyfikatu klucza#
NetHSM wspiera generowanie CSR (Certificate Signing Requests) dla przechowywanych kluczy.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Administrator lub Operator.
Wymagane opcje.
Opcja |
Opis |
---|---|
|
Identyfikator klucza, dla którego ma być wygenerowany CSR |
|
Nazwa kraju |
|
Nazwa państwa lub województwa |
|
Nazwa miejscowości |
|
Nazwa organizacji |
|
Nazwa jednostki organizacyjnej |
|
Nazwa zwyczajowa |
|
Adres e-mail. |
Przykład
$ nitropy nethsm --host $NETHSM_HOST csr --key-id myFirstKey --country="DE" --state-or-province="Berlin" --locality="Berlin" --organization="Nitrokey" --organizational-unit="" --common-name=nitrokey.com --email-address="info@nitrokey.com"
-----BEGIN CERTIFICATE REQUEST-----
MIHxMIGkAgEAMHExbzAJBgNVBAYTAkRFMA0GA1UEBwwGQmVybGluMA0GA1UECAwG
QmVybGluMA8GA1UECgwITml0cm9rZXkwEwYDVQQDDAxuaXRyb2tleS5jb20wHgYJ
KoZIhvcNAQkBFhFpbmZvQG5pdHJva2V5LmNvbTAqMAUGAytlcAMhADJMNAifke6s
u7CYqHGDy3xGtXVOUNbTJG6Gn4oki+j3oAAwBQYDK2VwA0EAQilRK2Mf6kfJ4ByI
WCn9A+8IHsnE7iFcuFZpmaKfcJwZiaQppHvPg/Z0zqldzviPQ1cjKR7hSZG+8GHH
gWjEDg==
-----END CERTIFICATE REQUEST-----
Informacje na temat punktu końcowego /keys/{KeyID}/csr.pem można znaleźć w dokumentacji API.
Kluczowe operacje#
Wszystkie operacje opisane w tym rozdziale mogą być wykonywane tylko dla kluczy, które znajdują się w *Namespace* bieżącego użytkownika.
Szyfruj#
NetHSM może szyfrować dane za pomocą kluczy symetrycznych, przechowywanych w sklepie Key Store. Natomiast szyfrowanie danych za pomocą kluczy asymetrycznych nie jest możliwe na NetHSM, ze względu na koncepcję kryptografii klucza publicznego, która zakłada udostępnienie klucza publicznego każdemu. Dla kluczy asymetrycznych NetHSM udostępnia klucz publiczny, który może być użyty do szyfrowania za pomocą zewnętrznego narzędzia. Więcej informacji na temat sposobu pobierania klucza publicznego klucza w sklepie Key Store można znaleźć na stronie Show Key Details .
Dane można zaszyfrować dla klucza symetrycznego w następujący sposób.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Operator.
Wymagane opcje.
Opcja |
Opis |
---|---|
|
Identyfikator klucza do szyfrowania danych |
|
Dane w kodowaniu Base64 |
|
Tryb szyfrowania |
|
Wektor inicjujący w kodowaniu Base64 |
Przykład
$ nitropy nethsm --host $NETHSM_HOST encrypt -k myFirstKey -d "TmV0SFNNIHJ1bGV6enp6enp6enp6enp6enp6enp6IQo=" -m AES_CBC -iv "aYlwUI4A9zL9tts4dMAq+A=="
Encrypted: Uk+9pgucdxTnbyIb/6+BDJef+HfRWhw+Eg3RcCvyHaU=
Initialization vector: aYlwUI4A9zL9tts4dMAq+A==
Informacje o punkcie końcowym /keys/{KeyID}/encrypt można znaleźć w dokumentacji API.
To drukuje zaszyfrowaną i zakodowaną w base64 wiadomość NetHSM rulezzzzzzzzzzzzzzzzzzz!
, oraz wektor inicjalizacji.
Dane można zaszyfrować dla kluczy asymetrycznych za pomocą OpenSSL w następujący sposób.
$ echo 'NetHSM rulez!' | openssl pkeyutl -encrypt -pubin -inkey public.pem | base64 > data.crypt
To zapisuje zaszyfrowaną i zakodowaną w base64 wiadomość NetHSM rulez!
do pliku data.crypt
, używając klucza publicznego z public.pem
.
Odszyfrować#
NetHSM może odszyfrować dane dla klucza prywatnego przechowywanego w Key Store na NetHSM. W tym przykładzie użyto zaszyfrowanej wiadomości z poprzedniego rozdziału Encrypt.
Obsługiwane tryby deszyfrowania są następujące.
TAG
PKCS1
FILENAME
--network
OAEP_SHA224
OAEP_SHA224
OAEP_SHA224
OAEP_SHA224
USER_ID
Dane można odszyfrować w następujący sposób.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Operator.
Wymagane opcje.
Opcja |
Opis |
---|---|
|
ID klucza do odszyfrowania danych szerokość |
|
Zaszyfrowane dane w kodowaniu Base64 |
|
Tryb odszyfrowania. Dostępne tryby są wymienione powyżej. |
Przykład
$ nitropy nethsm -h $NETHSM_HOST decrypt -k myFirstKey -d "$(cat data.crypt)" -m PKCS1 | base64 -d
NetHSM rulez!
Informacje na temat punktu końcowego /keys/{KeyID}/decrypt można znaleźć w dokumentacji API.
Podpisać#
NetHSM może podpisywać dane kluczem prywatnym przechowywanym w Key Store na NetHSM. W przypadku podpisu kluczem RSA i ECDSA należy najpierw obliczyć skrót.
Do obliczenia skrótu potrzebne są najpierw dane. Wiadomość tworzona jest w następujący sposób.
$ echo 'NetHSM rulez!' > data
Skrót obliczany jest za pomocą OpenSSL w następujący sposób.
$ openssl dgst -sha256 -binary data | base64 > data.digest
Obsługiwane tryby podpisywania są następujące.
PKCS1
USER_ID
FILENAME
Curve25519
Curve25519
Curve25519
Curve25519
PKCS1
PKCS1
Na podstawie skrótu można stworzyć podpis w następujący sposób.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Operator.
Wymagane opcje.
Opcja |
Opis |
---|---|
|
ID klucza do podpisywania szerokości danych |
|
Dane do podpisania zakodowane przy użyciu Base64 |
|
Tryb znakowy |
Przykład
$ nitropy nethsm -h $NETHSM_HOST sign -k myFirstKey -m PKCS1 -d "$(cat data.digest)" | base64 -d > data.sig
Informacje na temat punktu końcowego /keys/{KeyID}/sign można znaleźć w dokumentacji API.
Utworzony podpis można zweryfikować za pomocą OpenSSL w następujący sposób.
$ openssl dgst -sha256 -verify public.pem -signature data.sig -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:-1 data
Verified OK
Przypadkowa#
NetHSM może dostarczyć losowe bajty jako ciąg znaków Base64.
Wymagana rola.
Ta operacja wymaga uwierzytelnienia z rolą Operator.
Argumenty
Argument |
Opis |
---|---|
|
Bajty do pobrania |
Przykład
nitropy nethsm --host $NETHSM_HOST random 4
94A2rg==
Informacje na temat punktu końcowego /random można znaleźć w dokumentacji API.