Operace#
Tato kapitola popisuje provozní úlohy pro uživatele s rolí Administrator a Operator. Více informací o rolích naleznete v kapitole Role.
Důležité
Než začnete pracovat, přečtěte si informace na začátku tohoto dokumentu.
Správa klíčů#
Generování klíčů#
NetHSM může generovat páry klíčů. Doporučuje se zadat možnost ID klíče, abyste mu dali výstižný název.
Podporované typy klíčů a jim odpovídající mechanismy jsou následující.
Typ klíče |
Mechanismy |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Keys are assigned to the Namespace of the user that generates the key.
Klíč lze vygenerovat následujícím způsobem.
Požadovaná role
Tato operace vyžaduje ověření pomocí role Administrator.
Požadované možnosti
Možnost |
Popis |
---|---|
|
Typ generovaného klíče. Možné hodnoty pro argument |
|
Mechanismy pro generovaný klíč. Možné hodnoty pro argument |
|
Délka generovaného klíče |
Volitelné možnosti
Možnost |
Popis |
---|---|
|
ID vygenerovaného klíče |
Příklad
$ 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
Informace o koncovém bodu /keys/generate najdete v Dokumentaci rozhraní.
Importní klíč#
NetHSM může importovat stávající soukromé klíče do Úložiště klíčů.
Podporované typy klíčů a jim odpovídající mechanismy jsou následující.
Typ klíče |
Mechanismy |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Keys are assigned to the Namespace of the user that imports the key.
Soukromý klíč ze souboru PEM importujte do NetHSM následujícím způsobem.
Požadovaná role
Tato operace vyžaduje ověření pomocí role Administrator.
Argumenty
Argument |
Popis |
---|---|
|
Private key file in PEM format |
Volitelné možnosti
Možnost |
Popis |
---|---|
|
Mechanismy pro generovaný klíč. Možné hodnoty pro argument |
|
ID nového klíče |
|
Značka pro nový klíč |
Příklad
$ nitropy nethsm --host $NETHSM_HOST import-key \
--mechanism RSA_Signature_PSS_SHA256 \
--mechanism RSA_Decryption_PKCS1 \
--key-id myFirstKey \
mykey.pem
Key myFirstKey added to NetHSM localhost:8443
Informace o koncovém bodu /keys najdete v Dokumentaci rozhraní.
Private keys in raw format can be imported as follows.
Požadovaná role
Tato operace vyžaduje ověření pomocí role Administrator.
Požadované možnosti
Možnost |
Popis |
---|---|
|
Typ generovaného klíče. Možné hodnoty pro argument |
|
Mechanismy pro generovaný klíč. Možné hodnoty pro argument |
|
Prvočíslo p pro klíče RSA v kódování base64 |
|
Prvočíslo q pro klíče RSA v kódování base64 |
|
Veřejný exponent pro klíče RSA v kódování base64 |
|
Klíčová data pro klíče ED25519 nebo ECDSA_* v kódování base64. |
Volitelné možnosti
Možnost |
Popis |
---|---|
|
ID nového klíče |
|
Značka pro nový klíč |
Příklad
$ 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
Informace o koncovém bodu /keys najdete v Dokumentaci rozhraní.
Klíč k odstranění#
The NetHSM can delete keys from the Key Store. Users can only delete keys in their Namespace.
Požadovaná role
Tato operace vyžaduje ověření pomocí role Administrator.
Argumenty
Argument |
Popis |
---|---|
|
ID klíče, který má být odstraněn |
Příklad
$ nitropy nethsm --host $NETHSM_HOST delete-key myFirstKey
Key myFirstKey deleted on NetHSM localhost:8443
Informace o koncovém bodu /keys/{KeyID} naleznete v dokumentaci API.
Seznam klíčů#
The NetHSM can list all keys in the Key Store that are in the Namespace of the current user.
Seznam lze získat následujícím způsobem.
Požadovaná role
Tato operace vyžaduje ověření pomocí role Administrator nebo Operator.
Volitelné možnosti
Možnost |
Popis |
---|---|
|
Značka pro vyhledávání |
Příklad
$ 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
Informace o koncovém bodu /keys najdete v Dokumentaci rozhraní.
Zobrazit podrobnosti o klíči#
The NetHSM can output more detailed information about a stored key. Users can only access keys in their Namespace.
Podrobné informace lze získat takto.
Požadovaná role
Tato operace vyžaduje ověření pomocí role Administrator nebo Operator.
Příklad
$ 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
Informace o koncovém bodu /keys/{KeyID} naleznete v dokumentaci API.
Veřejný klíč klíče lze získat následujícím způsobem. Je ve formátu PKCS#8.
Požadovaná role
Tato operace vyžaduje ověření pomocí role Administrator nebo Operator.
Příklad
$ 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-----
Informace o koncovém bodě /keys/{KeyID}/public.pem naleznete v Dokumentaci API.
Veřejný klíč lze zkontrolovat například pomocí OpenSSL takto.
Požadovaná role
Tato operace vyžaduje ověření pomocí role Administrator nebo Operator.
Příklad
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-----
Informace o koncovém bodě /keys/{KeyID}/public.pem naleznete v Dokumentaci API.
Klíčové certifikáty#
Pro klíče uložené v zařízení NetHSM je možné nastavovat certifikáty a dotazovat se na ně.
Podporované typy MIME jsou následující.
application/x-pem-file
application/x-x509-ca-cert
application/pgp-keys
Certifikát lze nastavit takto.
Požadovaná role
Tato operace vyžaduje ověření pomocí role Administrator.
Požadované možnosti
Možnost |
Popis |
---|---|
|
ID klíče, pro který má být certifikát nastaven. |
Volitelné možnosti
Možnost |
Popis |
---|---|
|
Typ MIME certifikátu. Dostupné typy MIME jsou uvedeny výše. |
Argumenty
Argument |
Popis |
---|---|
|
Soubor s certifikátem |
Příklad
$ 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
Informace o koncovém bodě /keys/{KeyID}/cert naleznete v Dokumentaci rozhraní.
Certifikát lze získat následujícím způsobem.
Požadovaná role
Tato operace vyžaduje ověření pomocí role Administrator nebo Operator.
Požadované možnosti
Možnost |
Popis |
---|---|
|
ID klíče, pro který se má získat certifikát. |
Příklad
$ 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-----
Informace o koncovém bodě /keys/{KeyID}/cert naleznete v Dokumentaci rozhraní.
Žádosti o podepsání klíčových certifikátů#
NetHSM podporuje generování CSR (Certificate Signing Requests) pro uložené klíče.
Požadovaná role
Tato operace vyžaduje ověření pomocí role Administrator nebo Operator.
Požadované možnosti
Možnost |
Popis |
---|---|
|
ID klíče, pro který se má vygenerovat CSR. |
|
Název země |
|
Název státu nebo provincie |
|
Název lokality |
|
Název organizace |
|
Název organizační jednotky |
|
Společný název |
|
E-mailová adresa |
Příklad
$ 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-----
Informace o koncovém bodě /keys/{KeyID}/csr.pem naleznete v dokumentaci API.
Klíčové operace#
All operations described in this chapter can only be executed for keys that are in the Namespace of the current user.
Šifrování#
Zařízení NetHSM může šifrovat data pro symetrické klíče uložené v úložišti klíčů ** . Naproti tomu šifrování dat s asymetrickými klíči nelze v NetHSM provádět, protože v kryptografii veřejných klíčů platí koncepce, že veřejný klíč je dostupný všem. Pro asymetrické klíče poskytuje NetHSM veřejný klíč, který lze použít pro šifrování pomocí externího nástroje. Více informací o tom, jak získat veřejný klíč klíče, naleznete v části Show Key Details (Zobrazit podrobnosti o klíči) v části Key Store (Úložiště klíčů).
Data lze šifrovat pro symetrický klíč následujícím způsobem.
Požadovaná role
Tato operace vyžaduje ověření s rolí Operator.
Požadované možnosti
Možnost |
Popis |
---|---|
|
ID klíče, kterým se data šifrují. |
|
Data v kódování Base64 |
|
Režim šifrování |
|
Inicializační vektor v kódování Base64 |
Příklad
$ 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==
Informace o koncovém bodu /keys/{KeyID}/encrypt naleznete v Dokumentaci API.
Vypíše zašifrovanou a base64 zakódovanou zprávu NetHSM rulezzzzzzzzzzzzzzzzzzz!
a inicializační vektor.
Data pro asymetrické klíče lze pomocí OpenSSL šifrovat následujícím způsobem.
$ echo 'NetHSM rulez!' | openssl pkeyutl -encrypt -pubin -inkey public.pem | base64 > data.crypt
Tímto způsobem zapíšete zašifrovanou a base64 zakódovanou zprávu NetHSM rulez!
do souboru data.crypt
s použitím veřejného klíče z public.pem
.
Dešifrování#
Zařízení NetHSM může dešifrovat data pro soukromý klíč uložený v úložišti Key Store v zařízení NetHSM. Tento příklad používá zašifrovanou zprávu z předchozí kapitoly Encrypt.
Podporované režimy dešifrování jsou následující.
TAG
PKCS1
FILENAME
--network
OAEP_SHA224
OAEP_SHA224
OAEP_SHA224
OAEP_SHA224
USER_ID
Data lze dešifrovat následujícím způsobem.
Požadovaná role
Tato operace vyžaduje ověření s rolí Operator.
Požadované možnosti
Možnost |
Popis |
---|---|
|
ID klíče pro dešifrování šířky dat |
|
Šifrovaná data v kódování Base64 |
|
Režim dešifrování. Dostupné režimy jsou uvedeny výše. |
Příklad
$ nitropy nethsm -h $NETHSM_HOST decrypt -k myFirstKey -d "$(cat data.crypt)" -m PKCS1 | base64 -d
NetHSM rulez!
Informace o koncovém bodu /keys/{KeyID}/decrypt naleznete v Dokumentaci API.
Podepsat#
Zařízení NetHSM může podepisovat data pro soukromý klíč uložený v úložišti Key Store v zařízení NetHSM. Pro podpisy s klíčem RSA a ECDSA musí být nejprve vypočten digest.
Pro výpočet digestu je nejprve nutné získat data. Zpráva se vytvoří takto.
$ echo 'NetHSM rulez!' > data
Digest se vypočítá pomocí OpenSSL následujícím způsobem.
$ openssl dgst -sha256 -binary data | base64 > data.digest
Podporované režimy podepisování jsou následující.
PKCS1
USER_ID
FILENAME
Curve25519
Curve25519
Curve25519
Curve25519
PKCS1
PKCS1
Z digestu lze vytvořit podpis následujícím způsobem.
Požadovaná role
Tato operace vyžaduje ověření s rolí Operator.
Požadované možnosti
Možnost |
Popis |
---|---|
|
ID klíče pro podepisování šířky dat |
|
Data k podpisu zakódovaná pomocí Base64 |
|
Režim znamení |
Příklad
$ nitropy nethsm -h $NETHSM_HOST sign -k myFirstKey -m PKCS1 -d "$(cat data.digest)" | base64 -d > data.sig
Informace o koncovém bodě /keys/{KeyID}/sign najdete v Dokumentaci API.
Vytvořený podpis lze ověřit pomocí OpenSSL následujícím způsobem.
$ openssl dgst -sha256 -verify public.pem -signature data.sig -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:-1 data
Verified OK
Náhodný#
NetHSM může poskytnout náhodné bajty jako řetězec Base64.
Požadovaná role
Tato operace vyžaduje ověření s rolí Operator.
Argumenty
Argument |
Popis |
---|---|
|
Byty k načtení |
Příklad
nitropy nethsm --host $NETHSM_HOST random 4
94A2rg==
Informace o koncovém bodu /random najdete v Dokumentaci rozhraní.