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
`TAG`	`RSA_Decryption_RAW` `RSA_Decryption_PKCS1` `RSA_Decryption_OAEP_MD5` `RSA_Decryption_OAEP_SHA1`. `RSA_Decryption_OAEP_SHA224` `RSA_Decryption_OAEP_SHA256` `RSA_Decryption_OAEP_SHA384` `RSA_Decryption_OAEP_SHA512` `RSA_Signature_PKCS1` `RSA_Signature_PSS_MD5` `RSA_Signature_PSS_SHA1` `RSA_Signature_PSS_SHA224` `RSA_Signature_PSS_SHA256` `RSA_Signature_PSS_SHA384` `RSA_Signature_PSS_SHA512`
`Curve25519`	`EdDSA_Signature`
`USER_ID`	`EdDSA_Signature`
`USER_ID`	`EdDSA_Signature`
`USER_ID`	`EdDSA_Signature`
`USER_ID`	`EdDSA_Signature`
`USER_ID`	`AES_Encryption_CBC` `AES_Decryption_CBC`

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
`-p`, `--port` `INTEGER`	Typ generovaného klíče. Možné hodnoty pro argument `KEYTYPE` najdete v tabulce výše.
`-m`, `--mechanism` `MECHANISM`.	One or multiple mechanisms for the generated key. Possible values for the `MECHANISM` argument can be found in the table above.
`-l`, `--length` `INTEGER`.	Délka generovaného klíče

Volitelné možnosti

Možnost	Popis
`-k`, `--key-id` `TEXT`	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

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
`TAG`	`RSA_Decryption_RAW` `RSA_Decryption_PKCS1` `RSA_Decryption_OAEP_MD5` `RSA_Decryption_OAEP_SHA1`. `RSA_Decryption_OAEP_SHA224` `RSA_Decryption_OAEP_SHA256` `RSA_Decryption_OAEP_SHA384` `RSA_Decryption_OAEP_SHA512` `RSA_Signature_PKCS1` `RSA_Signature_PSS_MD5` `RSA_Signature_PSS_SHA1` `RSA_Signature_PSS_SHA224` `RSA_Signature_PSS_SHA256` `RSA_Signature_PSS_SHA384` `RSA_Signature_PSS_SHA512`
`Curve25519`	`EdDSA_Signature`
`USER_ID`	`EdDSA_Signature`
`USER_ID`	`EdDSA_Signature`
`USER_ID`	`EdDSA_Signature`
`USER_ID`	`EdDSA_Signature`
`USER_ID`	`AES_Encryption_CBC` `AES_Decryption_CBC`

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
`FILENAME`	Private key file in PEM format

Volitelné možnosti

Možnost	Popis
`-m`, `--mechanism` `MECHANISM`.	One or multiple mechanisms for the key. Possible values for the `MECHANISM` argument can be found in the table above.
`-k`, `--key-id` `TEXT`	ID nového klíče
`--tags` `TEXT`	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

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
`-p`, `--port` `INTEGER`	Typ generovaného klíče. Možné hodnoty pro argument `KEYTYPE` najdete v tabulce výše.
`-m`, `--mechanism` `MECHANISM`.	One or multiple mechanisms for the key. Possible values for the `MECHANISM` argument can be found in the table above.
`-u`, `--user-id` `TEXT`	Prvočíslo p pro klíče RSA v kódování base64
`-u`, `--user-id` `TEXT`	Prvočíslo q pro klíče RSA v kódování base64
`-e`, `--public-exponent` `TEXT`	Veřejný exponent pro klíče RSA v kódování base64
`-d`, `--data` `TEXT`	Klíčová data pro klíče ED25519 nebo ECDSA_* v kódování base64.

Volitelné možnosti

Možnost	Popis
`-k`, `--key-id` `TEXT`	ID nového klíče
`--tags` `TEXT`	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

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
`--time`	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

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
`-f`, `--filter` `TEXT`	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

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

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

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

Štítky pro klíče¶

Značky lze použít k nastavení jemných omezení přístupu ke klíčům a jsou volitelnou funkcí. Ke klíči lze přiřadit jeden nebo více Tagů. Uživatelé Operátor mohou vidět všechny klíče, ale používat pouze ty, které mají alespoň jeden odpovídající Tag. Pokud klávesa nemá žádný Tag, mohou ji používat všichni uživatelé Operator. Tag ** nemůže uživatel Operator měnit.

Informace o používání Tags na účtech Operátor naleznete v kapitole Tags for Users.

Poznámka

Uživatelé s rolí Administrator spravují Tags bez omezení.

Značku Tag lze přidat následujícím způsobem.

Požadovaná role

Tato operace vyžaduje ověření pomocí role Administrator.

Argumenty

Argument	Popis
`--time`	ID klíče, na který se nastaví značka
`TAG`	Značka, která se nastaví na klíči

Příklad

$ nitropy nethsm --host $NETHSM_HOST add-key-tag myFirstKey berlin

Added tag berlin for key myFirstKey on the NetHSM localhost:8443

Značku Tag lze odstranit následujícím způsobem.

Požadovaná role

Tato operace vyžaduje ověření pomocí role Administrator.

Argumenty

Argument	Popis
`--time`	ID klíče, na který se má značka nastavit.
`TAG`	Značka, která se nastaví na klíči.

Příklad

$ nitropy nethsm --host $NETHSM_HOST delete-key-tag myFirstKey berlin

Deleted tag berlin for key myFirstKey on the NetHSM localhost:8443

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
`-k`, `--key-id` `TEXT`	ID klíče, pro který má být certifikát nastaven.

Volitelné možnosti

Možnost	Popis
`-m`, `--mechanism` `MECHANISM`.	Typ MIME certifikátu. Dostupné typy MIME jsou uvedeny výše.

Argumenty

Argument	Popis
`FILENAME`	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

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
`-k`, `--key-id` `TEXT`	ID klíče, pro který se má získat certifikát.

Příklad

$ nitropy nethsm --host $NETHSM_HOST get-certificate --key-id myFirstKey

Žá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
`-k`, `--key-id` `TEXT`	ID klíče, pro který se má vygenerovat CSR.
`--country` `TEXT`	Název země
`--state-or-province` `TEXT`	Název státu nebo provincie
`--locality` `TEXT`	Název lokality
`--organization` `TEXT`	Název organizace
`--organizational-unit` `TEXT`	Název organizační jednotky
`--common-name` `TEXT`	Společný název
`--email-address` `TEXT`	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"

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
`-k`, `--key-id` `TEXT`	ID klíče, kterým se data šifrují.
`-d`, `--data` `TEXT`	Data v kódování Base64
`-m`, `--mode` `[AES_CBC]`	Režim šifrování
`-iv`, `--initialization-vector` `TEXT`	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==

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
`-k`, `--key-id` `TEXT`	ID klíče pro dešifrování šířky dat
`-d`, `--data` `TEXT`	Šifrovaná data v kódování Base64
`-d`, `--data` `TEXT`	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!

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
`-k`, `--key-id` `TEXT`	ID klíče pro podepisování šířky dat
`-d`, `--data` `TEXT`	Data k podpisu zakódovaná pomocí Base64
`-d`, `--data` `TEXT`	Režim znamení

Příklad

$ nitropy nethsm -h $NETHSM_HOST sign \
   -k myFirstKey \
   -m PKCS1 \
   -d "$(cat data.digest)" | base64 -d > data.sig

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
`--time`	Byty k načtení

Příklad

nitropy nethsm --host $NETHSM_HOST random 4

94A2rg==