Operation#

This chapter describes operational tasks for users with the Administrator and Operator role. Please refer to chapter Roles to learn more about the role.

Important

Please make sure you read the information in the beginning of this document before starting to work.

Key Management#

Generate Key#

The NetHSM can generate key pairs. It is recommended to specify the key ID option to give it an expressive name.

The supported key types and their corresponding mechanisms are the following.

Key Type	Mechanisms
`RSA`	`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`
`EC_P224`	`ECDSA_Signature`
`EC_P256`	`ECDSA_Signature`
`EC_P384`	`ECDSA_Signature`
`EC_P521`	`ECDSA_Signature`
`Generic`	`AES_Encryption_CBC` `AES_Decryption_CBC`

The key can be generated as follows.

Required Role

This operation requires an authentication with the Administrator role.

Required Options

Option	Description
`-t`, `--type` `KEYTYPE`	The type for the generated key. Possible values for the `KEYTYPE` argument can be found in the table above.
`-m`, `--mechanism` `MECHANISM`	The mechanisms for the generated key. Possible values for the `MECHANISM` argument can be found in the table above.
`-l`, `--length` `INTEGER`	The length of the generated key

Optional Options

Option	Description
`-k`, `--key-id` `TEXT`	The ID of the generated key

Example

$ 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

Import Key#

The NetHSM can import existing private keys to the Key Store.

The supported key types and their corresponding mechanisms are the following.

Key Type	Mechanisms
`RSA`	`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`
`EC_P224`	`ECDSA_Signature`
`EC_P256`	`ECDSA_Signature`
`EC_P384`	`ECDSA_Signature`
`EC_P521`	`ECDSA_Signature`
`Generic`	`AES_Encryption_CBC` `AES_Decryption_CBC`

The import can be initiated as follows.

Required Role

This operation requires an authentication with the Administrator role.

Required Options

Option	Description
`-t`, `--type` `KEYTYPE`	The type for the generated key. Possible values for the `KEYTYPE` argument can be found in the table above.
`-m`, `--mechanism` `MECHANISM`	The mechanisms for the generated key. Possible values for the `MECHANISM` argument can be found in the table above.
`-p`, `--prime-p` `TEXT`	The prime p for RSA keys, base64-encoded
`-q`, `--prime-q` `TEXT`	The prime q for RSA keys, base64-encoded
`-e`, `--public-exponent` `TEXT`	The public exponent for RSA keys, base64 encoded
`-d`, `--data` `TEXT`	The key data for ED25519 or ECDSA_* keys, base64-encoded

Optional Options

Option	Description
`-k`, `--key-id` `TEXT`	The ID of the new key
`--tags` `TEXT`	The Tag for the new key

Example

$ 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

Delete Key#

The NetHSM can delete keys from the Key Store.

Required Role

This operation requires an authentication with the Administrator role.

Arguments

Argument	Description
`KEY_ID`	The key ID of the key to delete

Example

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

Key myFirstKey deleted on NetHSM localhost:8443

List Keys#

The NetHSM can list all the available keys in the Key Store.

The list can be retrieved as follows.

Required Role

This operation requires an authentication with the Administrator or Operator role.

Optional Options

Option	Description
`-f`, `--filter` `TEXT`	The Tag to search for

Example

$ 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

Show Key Details#

The NetHSM can output more detailed information about a stored key.

The detailed information can be retrieved as follows.

Required Role

This operation requires an authentication with the Administrator or Operator role.

Example

$ 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

The public key of a key can be retrieved as follows. It’s in PKCS#8 format.

Required Role

This operation requires an authentication with the Administrator or Operator role.

Example

$ nitropy nethsm --host $NETHSM_HOST get-key myFirstKey --public-key

The public key can be inspected for example with OpenSSL as follows.

Required Role

This operation requires an authentication with the Administrator or Operator role.

Example

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

Tags for Keys#

Tags can be used to set fine-grained access restrictions on keys, and are an optional feature. One or more Tags can be assigned to a key. The Operator users can see all keys, but only use those with at least one corresponding Tag. If a key has no Tag it can be used by all Operator users. A Tag can not be modified by an Operator user.

To learn about how to use Tags on Operator accounts, please refer to chapter Tags for Users.

Note

Tags are managed without restrictions by users with the Administrator role.

The Tag can be added as follows.

Required Role

This operation requires an authentication with the Administrator role.

Arguments

Argument	Description
`KEY_ID`	The key ID to set the tag on
`TAG`	The tag to set on the key

Example

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

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

The Tag can be deleted as follows.

Required Role

This operation requires an authentication with the Administrator role.

Arguments

Argument	Description
`KEY_ID`	The key ID to set the tag on.
`TAG`	The tag to set on the key.

Example

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

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

Key Certificates#

It is possible to set and query certificates for the keys stored on a NetHSM.

The supported MIME types are as follows.

application/x-pem-file
application/x-x509-ca-cert
application/pgp-keys

The certificate can be set as follows.

Required Role

This operation requires an authentication with the Administrator role.

Required Options

Option	Description
`-k`, `--key-id` `TEXT`	The ID of the key to set the certificate for

Optional Options

Option	Description
`-m`, `--mime-type` `MIME_TYPE`	The MIME type of the certificate. The available MIME types are listed above.

Arguments

Argument	Description
`FILENAME`	Certificate file

Example

$ 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

The certificate can be retrieved as follows.

Required Role

This operation requires an authentication with the Administrator or Operator role.

Required Options

Option	Description
`-k`, `--key-id` `TEXT`	The ID of the key to get the certificate for

Example

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

Key Certificate Signing Requests#

The NetHSM supports generating CSR (Certificate Signing Requests) for the stored keys.

Required Role

This operation requires an authentication with the Administrator or Operator role.

Required Options

Option	Description
`-k`, `--key-id` `TEXT`	The ID of the key to generate the CSR for
`--country` `TEXT`	The country name
`--state-or-province` `TEXT`	The state or province name
`--locality` `TEXT`	The locality name
`--organization` `TEXT`	The organization name
`--organizational-unit` `TEXT`	The organization unit name
`--common-name` `TEXT`	The common name
`--email-address` `TEXT`	The email address

Example

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

Key Operations#

Encrypt#

The NetHSM can encrypt data for symmetric keys, stored in the Key Store. In contrast encrypting data with asymmetric keys can not be done on the NetHSM, because of the concept in public-key cryptography to make the public key available to everybody. For asymmetric keys the NetHSM provides the public key, which can be used for encryption with an external tool. Please refer to the Show Key Details to learn more about how to retrieve the public key of a key in the Key Store.

Data can be encrypted for a symmetric key as follows.

Required Role

This operation requires an authentication with the Operator role.

Required Options

Option	Description
`-k`, `--key-id` `TEXT`	The ID of the key to encrypt the data with
`-d`, `--data` `TEXT`	The data in Base64 encoding
`-m`, `--mode` `[AES_CBC]`	The encrypt mode
`-iv`, `--initialization-vector` `TEXT`	The initialization vector in Base64 encoding

Example

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

This prints the encrypted and base64 encoded message NetHSM rulezzzzzzzzzzzzzzzzzzz!, and the initialization vector.

Data can be encrypted for asymmetric keys with OpenSSL as follows.

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

This writes the encrypted and base64 encoded message NetHSM rulez! into the file data.crypt, using the public key from public.pem.

Decrypt#

The NetHSM can decrypt data for an private key stored in the Key Store on the NetHSM. This example uses the encrypted message from the previous chapter Encrypt.

The supported decrypt modes are as follows.

RAW
PKCS1
OAEP_MD5
OAEP_SHA1
OAEP_SHA224
OAEP_SHA256
OAEP_SHA384
OAEP_SHA512
AES_CBC

The data can be decrypted as follows.

Required Role

This operation requires an authentication with the Operator role.

Required Options

Option	Description
`-k`, `--key-id` `TEXT`	The ID of the key to decrypt the data width
`-d`, `--data` `TEXT`	The encrypted data in Base64 encoding
`-m`, `--mode` `MODE`	The decrypt mode. Available modes are listed above.

Example

$ nitropy nethsm -h $NETHSM_HOST decrypt -k myFirstKey -d "$(cat data.crypt)" -m PKCS1 | base64 -d

NetHSM rulez!

Sign#

The NetHSM can sign data for a private key stored in the Key Store on the NetHSM. For signatures with a RSA and ECDSA key, a digest must be calculate first.

To calculate a digest the data is required first. A message is created as follows.

$ echo 'NetHSM rulez!' > data

The digest is calculated with OpenSSL as follows.

$ openssl dgst -sha256 -binary data | base64 > data.digest

The supported signing modes are as follows.

PKCS1
PSS_MD5
PSS_SHA1
PSS_SHA224
PSS_SHA256
PSS_SHA384
PSS_SHA512
EdDSA
ECDSA

From the digest a signature can be created as follows.

Required Role

This operation requires an authentication with the Operator role.

Required Options

Option	Description
`-k`, `--key-id` `TEXT`	The ID of the key to sign the data width
`-d`, `--data` `TEXT`	The data to sign encoded using Base64
`-m`, `--mode` `MODE`	The sign mode

Example

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

The created signature can be verified with OpenSSL as follows.

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

Verified OK

Random#

The NetHSM can provide random bytes as a Base64 string.

Required Role

This operation requires an authentication with the Operator role.

Arguments

Argument	Description
`LENGTH`	Bytes to retrieve

Example

nitropy nethsm --host $NETHSM_HOST random 4

94A2rg==