Administration#

This chapter describes administrative tasks for users with the Administrator 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.

System Management#

Device Information#

The vendor and product information for a NetHSM can be retrieved as follows.

Example

$ nitropy nethsm --host $NETHSM_HOST info
Host:    localhost:8443
Vendor:  Nitrokey GmbH
Product: NetHSM

Boot Mode#

NetHSM can be used in Attended Boot mode and Unattended Boot mode.

Boot Mode

Description

Attended Boot

The NetHSM boots up into a _Locked_ state. The Unlock Passphrase needs to be entered during each start, which is used to decrypt the User Data. For security reasons, this mode is recommended and it’s the default mode for a freshly provisioned system.

Unattended Boot

The system starts unattended without the need to enter the Unlock Passphrase into an _Operational_ state. Use this mode if your availability requirements can not be fulfilled with Attended Boot mode.

Warning

Regardless of the boot mode, the Unlock Passphrase retains its validity and is required for restoring backups on other hardware. Keep the Unlock Passphrase safe at any time.

The current boot mode can be retrieved as follows.

Example

$ nitropy nethsm --host $NETHSM_HOST get-config --unattended-boot
Configuration for NetHSM localhost:8443:
   Unattended boot: off

The boot mode can be changed as follows. At next boot, the NetHSM will behave accordingly.

Arguments

Argument

Description

Status

Enable or disable Unattended Boot. Can have value on or off.

Example

$ nitropy nethsm --host $NETHSM_HOST set-unattended-boot on
Updated the unattended boot configuration for NetHSM localhost:8443

State#

The NetHSM software has four states: Unprovisioned, Provisioned, Locked, and Operational.

State

Description

Unprovisioned

NetHSM without configuration (factory default)

Provisioned

NetHSM with configuration. The Provisioned state implies either Operational or Locked state.

Operational

NetHSM with configuration and ready to execute commands. The Operational state implies the Provisioned state.

Locked

NetHSM with configuration but encrypted and inaccessible data stores. Typically, the next step is to unlock the system. The Locked state implies the Provisioned state.

States and transitions of the NetHSM

States and transitions of the NetHSM#


The current state of the NetHSM can be retrieved as follows.

Example

$ nitropy nethsm --host $NETHSM_HOST state
NetHSM localhost:8443 is Unprovisioned

A new NetHSM has an Unprovisioned state and after provisioning enters the Operational state. The provisioning of a NetHSM is described in the chapter Provisioning.

A NetHSM in Operational state can be locked again to protect it as follows.

Example

$ nitropy nethsm --host $NETHSM_HOST lock
NetHSM localhost:8443 locked

A NetHSM in Locked state can be unlocked as follows. While the NetHSM is in the _Locked_ state no other operations are possible. Afterwards the NetHSM is in an _Operational_ state.

Example

$ nitropy nethsm --host $NETHSM_HOST unlock
NetHSM localhost:8443 unlocked

Unlock Passphrase#

The Unlock Passphrase is used to derive an Unlock Key if the NetHSM is in Locked state. The passphrase is initially set during provisioning of the NetHSM.

Warning

The unlock passphrase cannot be reset without knowing the current value. If the unlock passphrase is lost, neither can it be reset to a new value nor can the NetHSM be unlocked.

The Unlock Passphrase can be set as follows.

Optional Options

Option

Description

-n, --new-passphrase TEXT

The new unlock passphrase

-p, --current-passphrase TEXT

The current unlock passphrase

-f, --force

Do not ask for confirmation before changing the passphrase

Example

$ nitropy nethsm --host $NETHSM_HOST set-unlock-passphrase
New passphrase:
Repeat for confirmation:
Current passphrase:
Warning: The unlock passphrase cannot be reset without knowing the current value. If the unlock passphrase is lost, neither can it be reset to a new value nor can the NetHSM be unlocked.
Do you want to continue? [y/N]: y
Updated the unlock passphrase for NetHSM localhost:8443

TLS Certificate#

The TLS certificate is used for the HTTPS based REST API, and thus also used by nitropy. During provisioning a self-signed certificate is created. The certificate can be replaced, for example with a signed certificate from a certificate authority (CA). In this case a Certificate Signing Request (CSR) must be generated. After signing the certificate must be imported to the NetHSM.

A change is only necessary when the certificate is to be replace. Such change may be to replace it with a signed certificate from a certificate authority (CA).

The TLS certificate can be retrieved as follows.

Required Options

Option

Description

-a, --api

Set the certificate for the NetHSM TLS interface

Example

$ nitropy nethsm --host $NETHSM_HOST get-certificate --api
-----BEGIN CERTIFICATE-----
MIIBHzCBxaADAgECAgkA7AznVQK3XWkwCgYIKoZIzj0EAwIwFDESMBAGA1UEAwwJ
a2V5ZmVuZGVyMCAXDTcwMDEwMTAwMDAwMFoYDzk5OTkxMjMxMjM1OTU5WjAUMRIw
EAYDVQQDDAlrZXlmZW5kZXIwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAARbeCRl
F1ZIjK1bTfrPvtCoYDThMjdV1q8mq+B9FMDo4GIahTCUG/Ub6bCOcbip5pP92J3h
yMEcPuos72c1KcGjMAoGCCqGSM49BAMCA0kAMEYCIQC/BNrkCM5gpsVfa9EqQcM0
PCaADyZG7KKLgDv7asa5LwIhAKDXRE3Tdm9tYObO0X4p0CRQkl1+DnvGljzQe34C
JBax
-----END CERTIFICATE-----

The TLS certificate can be generated as follows.

Required Options

Option

Description

-t, --type [RSA|Curve25519|EC_P224|EC_P256|EC_P384|EC_P521]

The type for the generated key

-l, --length INTEGER

The length of the generated key

Example

$ nitropy nethsm --host $NETHSM_HOST generate-tls-key -t Curve25519
Key for TLS interface generated on NetHSM localhost:8443

The Certificate Signing Request (CSR) for the certificate can be generated as follows.

Required Options

Option

Description

-a, --api

Generate a CSR for the NetHSM TLS certificate

--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 --api --country="DE" --state-or-province="Berlin" --locality="Berlin" --organization="Nitrokey" --organizational-unit="" --common-name="Nitrokey" --email-address="info@nitrokey.com"
-----BEGIN CERTIFICATE REQUEST-----
MIGBMDUCAQAwAjEAMCowBQYDK2VwAyEAE+nz+nOj80SWG25UbqVcQk6Ua84zuj5B
9qCtPpDUX2qgADAFBgMrZXADQQDwk9LrYDu83a1jgBGqW0I9BVXWEhP4gZLxlVV+
c102GFi963ZPIxG7Z5+uWplz+wr/Vmr7KLr6oM01M/AZPJQO
-----END CERTIFICATE REQUEST-----

The certificate can be replaced as follows.

Required Options

Option

Description

-a, --api

Set the certificate for the NetHSM TLS interface

Arguments

Argument

Description

FILENAME

Certificate file

Example

nitropy nethsm --host $NETHSM_HOST set-certificate --api /tmp/nethsm-certificate

Network#

The network configuration defines the settings used for the Network Port.

Note

This settings do not configure the BMC Network Port.

The network configuration can be retrieved as follows.

Required Options

Option

Description

--network

Query the network configuration

Example

$ nitropy nethsm -h $NETHSM_HOST get-config --network
Configuration for NetHSM localhost:8443:
Network:
      IP address:    192.168.1.1
      Netmask:       255.255.255.0
      Gateway:       0.0.0.0

Set the network configuration as follows.

Note

The NetHSM does not support DHCP (Dynamic Host Configuration Protocol).

Note

The NetHSM does not support IPv6 (Internet Protocol version 6).

Required Options

Option

Description

-a, --ip-address

The new IP address

-n, --netmask

The new netmask

-g, --gateway

The new gateway

Example

$ nitropy nethsm -h $NETHSM_HOST set-network-config -a 192.168.1.1 -n 255.255.255.0 -g 0.0.0.0
Updated the network configuration for NetHSM localhost:8443

Time#

The time configuration sets the system time of the NetHSM software. It is usually not required to set the system time, as it is set during provisioning.

The time configuration can be retrieved as follows.

Required Options

Option

Description

--time

Query the system time

Example

$ nitropy nethsm -host $NETHSM_HOST get-config --time
Configuration for NetHSM localhost:8443:
Time:            2022-08-17 11:40:00+00:00

Set the time of the NetHSM.

Important

Make sure to pass the time in UTC timezone.

Arguments

Argument

Description

time

The system time to set (Format: YYYY-MM-DDTHH:MM:SSZ)

Example

$ nitropy nethsm -h $NETHSM_HOST set-time 2022-08-17T11:40:00Z
Updated the system time for NetHSM localhost:8443

Metrics#

The NetHSM logs metrics of system parameters. Please refer to Metrics to learn more about each metric.

The metrics can be retrieved as follows.

Required Role

This operation requires an authentication with the Metrics role.

Example

$ nitropy nethsm -h $NETHSM_HOST metrics
Metric                         Value
----------------------------   --------
client connections             0
established state              6
external.received bytes        989931
external.received packets      13239
external.transmitted bytes     25908953
external.transmitted packets   22037
free chunk count               322
gc compactions                 0
gc major bytes                 21348352
gc major collections           35
gc minor collections           2652
http response 200              28
http response 201              1
http response 204              1
http response 400              1
http response 403              1
http response 404              145
http response 412              1
http response time             0.084998
http response total            178
internal.received bytes        66541
internal.received packets      1130
internal.transmitted bytes     63802
internal.transmitted packets   1133
kv write                       2
log errors                     3
log warnings                   3
maximum allocated space        64528384
maximum releasable bytes       1216
mmapped region count           0
new sleeper size               1
non-mmapped allocated bytes    64528384
sleep queue size               11
syn-rcvd state                 0
timers                         2
total allocated space          43940832
total client                   1
total established              515
total free space               20587552
total sleeper size             12
total syn-rcvd                 514
total timers                   526
uptime                         17626

Logging#

The NetHSM can log system events to the serial port or to a syslog server on the network.

Important

For any production deployment, the NetHSM log should be monitored continuously to provide immediate notification of any potential security issues.

The syslog server configuration can be retrieved as follows.

Required Options

Option

Description

--logging

Query the logging configuration

Example

$ nitropy nethsm -h $NETHSM_HOST get-config --logging
Logging:
   IP address:    0.0.0.0
   Port:          514
   Log level:     info

The syslog server configuration can be set as follows.

Required Options

Option

Description

-a, --ip-address TEXT

The IP address of the new logging destination

-p, --port INTEGER

The port of the new logging destination

-l, --log-level [debug|info|warning|error]

The new log level

Example

$ nitropy nethsm -h $NETHSM_HOST set-logging-config -a 192.168.0.1 -p 514 -l info
Updated the logging configuration for NetHSM localhost:8443

The serial console works right from the start of the NetHSM hardware. It includes events from the NetHSM firmware and the NetHSM software.

The serial console connection settings are as follows.

Setting

Value

Baud rate

115200

Data bits

8

Stop bits

1

Parity

None

Flow Control

None

Backup#

The NetHSM User Data can be saved to a backup file. This backup file contains all User Data, namely Configuration Store, Authentication Store, Domain Key Store and Key Store.

Important

A NetHSM system software in Unattended Boot mode will require the Unlock Passphrase if restored on a different NetHSM hardware. Please refer to chapter Unlock Passphrase to learn more.

Important

A NetHSM in Unattended Boot mode will be in the same mode after a restore.

Before a backup can be initiated the Backup Passphrase must be set. The Backup Passphrase is used to encrypt the data in the backup file.

Warning

The backup passphrase cannot be reset without knowing the current value. If the backup passphrase is lost, neither can it be reset to a new value nor can the created backups be restored.

The backup passphrase can be set as follows.

Optional Options

Option

Description

-n, --new-passphrase TEXT

The new backup passphrase

-p, --current-passphrase TEXT

The current backup passphrase (or an empty string if not set)

-f, --force

Do not ask for confirmation before changing the passphrase

Example

$ nitropy nethsm -h $NETHSM_HOST -u admin set-backup-passphrase
New passphrase:
Repeat for confirmation:
Warning: The backup passphrase cannot be reset without knowing the current value. If the backup passphrase is lost, neither can it be reset to a new value nor can the created backups be restored.
Do you want to continue? [y/N]: y
The current backup passphrase (or an empty string if not set) []:
Updated the backup passphrase for NetHSM localhost:8443

The backup can be executed as follows.

Required Role

This operation requires an authentication with the Backup role.

Arguments

Argument

Description

FILENAME

Backup file

Example

$ nitropy nethsm -h $NETHSM_HOST backup /tmp/nethsm-backup
Backup for localhost:8443 written to /tmp/backup

Restore#

The NetHSM can be restored from a backup file.

  • If the NetHSM is Unprovisioned it will restore all User Data including system configuration and reboot. Therefore the system may get different network settings, TLS certificate and Unlock Passphrase afterwards.

  • If the NetHSM is Provisioned it will restore users and user keys but not system configuration. In this case all previously existing users and user keys will be deleted. The NetHSM ends in an Operational state.

The restore can be applied as follows.

Optional options

Option

Description

-p, --backup-passphrase passphrase

The Backup Passphrase

-t, --system-time

The system time to set (Format: YYYY-MM-DDTHH:MM:SSZ)

Important

Make sure the time of your local computer is correctly set. To set a different time, please provide it manually.

Arguments

Argument

Description

FILENAME | Restore file

Example

$ nitropy nethsm -h $NETHSM_HOST restore /tmp/nethsm-backup
Backup passphrase:
Backup restored on NetHSM localhost:8443

Clustering#

NetHSM is stateless, so that several NetHSM devices can be used to process extremely high throughput and provide high availability. The PKCS#11 module supports round-robin schedule for a cluster of NetHSM instances. Multiple instances of NetHSM can be synchronized via encrypted backups. For this a separate system downloads and uploads backup files between the instances. This separate system doesn’t have access to the backup data in clear text because the backup files are encrypted. The synchronization can be easily scripted by using pynitrokey as shown in this example.

Software Update#

Software updates can be installed in a two-step process. First the update image needs to be uploaded to a Provisioned NetHSM. The NetHSM verifies image authenticity, integrity, and version number. Optionally, the NetHSM displays release notes, if any.

Warning

Data loss may occur due to the installation of a beta update! Stable versions should not cause data loss. However, it’s recommended to create a backup before updating.

The update file can be uploaded as follows.

Arguments

Argument

Description

FILENAME

Update file

Example

$ nitropy nethsm --host $NETHSM_HOST update /tmp/nethsm-update.img.bin
Image /tmp/nethsm-update.img.bin uploaded to NetHSM localhost:8443

Afterwards the update can be applied or aborted. Please refer to the desired option below. If the NetHSM is powered down before the “commit” operation, the update file has to be uploaded again.

Important

If the upload of the update image fails with Error: NetHSM request failed: Bad request -- malformed image, please follow the steps below.

  1. Make sure you have a valid update file by checking with the provided signature.

  2. Make sure you don’t have a high log level, such as DEBUG enabled. Please refer to chapter Logging to learn more about the log level configuration.

  3. Reboot the appliance to free up used memory.

The update can be applied (committed) as follows. Any data migration is only performed after the NetHSM has successfully booted the new system software version.

Example

$ nitropy nethsm --host $NETHSM_HOST commit-update
Update successfully committed on NetHSM localhost:8443

The update can be cancelled as follows.

Example

$ nitropy nethsm --host $NETHSM_HOST cancel-update
Update successfully cancelled on NetHSM localhost:8443

System Information#

System information such as firmware version, software version, and hardware version can be retrieved as follows.

Example

$ nitropy nethsm -h $NETHSM_HOST system-info
Host:             192.168.1.1
Firmware version: 1.0-prod
Software version: 2.0
Hardware version: prodrive-hermes-1.0
Build tag:        v2.0-0-g17ad829

Reboot and Shutdown#

The NetHSM can be rebooted and shutdown, either remotely, or with the restart and poweroff button on the front of the NetHSM hardware.

The remote reboot can be initiated as follows.

Example

$ nitropy nethsm --host $NETHSM_HOST reboot
NetHSM localhost:8443 will be rebooted.
Do you want to continue? [y/N]: y
NetHSM localhost:8443 is about to reboot

The remote shutdown can be initiated as follows.

Example

$ nitropy nethsm --host $NETHSM_HOST shutdown
NetHSM localhost:8443 will be shutdown.
Do you want to continue? [y/N]: y
NetHSM localhost:8443 is about to shutdown

Reset to Factory Defaults#

A Provisioned NetHSM can be reset to factory defaults. In this case all user data is securely deleted and the NetHSM boots into an Unprovisioned state. Afterwards, you may want to provision the NetHSM.

The reset to factory defaults can be performed as follows.

Example

$ nitropy nethsm -h $NETHSM_HOST factory-reset
NetHSM localhost:8443 will be set to factory defaults.
All data will be lost!
Do you want to continue? [y/N]: y
NetHSM localhost:8443 is about to perform a factory reset

User Management#

Roles#

The NetHSM allows the separation of duties by using different roles. Each user account configured on the NetHSM has one of the following Roles assigned to it.

Role

Description

Administrator

A user account with this Role has access to all operations provided by the NetHSM, except for key usage operations, i.e. message signing and decryption.

Operator

A user account with this Role has access to all key usage operations, a read-only subset of key management operations and user management operations allowing changes to their own account only.

Metrics

A user account with this Role has access to read-only metrics operations only.

Backup

A user account with this Role has access to the operations required to initiate a system backup only.

See Namespaces and Tags for more fine-grained access restricions.

Note

In a future release, additional Roles may be introduced.

Add User#

Add a user account to the NetHSM. Each user account has a Role, which needs to be specified. Please refer to chapter Roles to learn more about Roles.

Optionally, a user can be assigned to a *Namespace*.

Note

The user ID must be alphanumeric. The NetHSM assigns a random user ID if none is specified.

A user account can be added as follows.

Required Options

Option

Description

-n, --real-name TEXT

The real name of the new user

-N, --namespace TEXT

The Namespace of the new user

-r, --role [Administrator|Operator|Metrics|Backup]

The Role of the new user

-p, --passphrase TEXT

The passphrase of the new user

Optional Options

Option

Description

-u, --user-id TEXT

The user ID of the new user

Example

$ nitropy nethsm --host $NETHSM_HOST  add-user --real-name "Nitrokey Operator" --role Operator --user-id operator1
Passphrase:
Repeat for confirmation:
User operator1 added to NetHSM localhost:8443

By default, the Namespace is inherited from the user that adds the new user. Only users without a Namespace can choose a different Namespace for new users. The Namespace is used as a prefix for the user name, for example namespace~user. Therefore, the same user name can be used in several Namespaces.

Delete User#

Delete a user account from the NetHSM.

Warning

Deletion is permanent and can not be reverted.

A user account can be deleted as follows.

Arguments

Argument

Description

USER_ID

The user Id of the user.

Example

$ nitropy nethsm --host $NETHSM_HOST delete-user operator1
User operator1 deleted on NetHSM localhost:8443

List Users#

List the users on the NetHSM.

The list can be retrieved as follows.

Optional Options

Option

Description

--details, --no-details

Query the real name and role of the user

Example

$ nitropy nethsm --host $NETHSM_HOST list-users
Users on NetHSM localhost:8843:

User ID        Real name               Role
---------      -----------------       -------------
operator1      Nitrokey Operator       Operator
admin          admin                   Administrator

Users within a Namespace can only see users in the same Namespace.

User Passphrase#

The passphrase of a user account can be reset. A passphrase is initial set during adding of a user account.

Note

Passphrases must have >= 10 and <= 200 characters.

The user passphrase can be set as follows.

Required Options

Option

Description

-u, --user-id TEXT

The user ID of the user

-p, --passphrase TEXT

The new passphrase of the user

Example

$ nitropy nethsm --host $NETHSM_HOST set-passphrase --user-id operator1
Passphrase:
Repeat for confirmation:
Updated the passphrase for user operator1 on NetHSM localhost:8443

Namespaces#

Namespaces were introduced in software version 2.0. When migrating from an earlier version of the software, all existing users and keys will be without a Namespace.

Similarly to the concept of partitions, NetHSM supports the more flexible Namespaces which group keys, administrators, and users on a NetHSM into separate subsets. Users can only see and use keys in the same Namespace and can only see users in the same Namespace. It is not possible to see users and to see and use keys of other Namespaces. When a new user is created, it inherits the Namespace of the user that created it. The available storage capacity is shared between all Namespaces.

Users with the Administrator Role are also referred to as R-Administrator if they are not in a Namespace, or N-Administrator if they are in a Namespace.

Special rules apply to R-Administrator users: They can set the Namespace for new users, list all users and query the Namespace of a user. Also, the NetHSM configuration can only be accessed by R-Administrator users. R-Administrators can not see keys in a Namespace.

To be able to generate keys and users in a Namespace, the Namespace needs to be created by an R-Administrator user. Once the Namespace has been created, R-Administrator users can no longer create, delete or modify users in that Namespace. This allows to protect Namespaces’ keys being accessed by R-Administrator (also indirectly by adding a new user on behalf or resetting existing user’s or administrator’s credentials). Therefore, it is necessary to create an N-Administrator user for the Namespace before creating the Namespace. R-Administrator users can also delete a Namespace with all contained keys.

List Namespaces#

List the Namespaces on the NetHSM.

The list can be retrieved as follows.

Example

$ nitropy nethsm --host $NETHSM_HOST list-namespaces
Namespaces on NetHSM localhost:8843:
- ns1
- ns2

Add Namespace#

Add a Namespace to the NetHSM.

R-Administrator users can already create new accounts in the Namespace before it is created. After the creation, only N-Administrator users can manage the users in the Namespace. The creation and usage of keys in the Namespace is only possible after it has been added.

Note

The Namespace ID must be alphanumeric. The NetHSM assigns a random user ID if none is specified.

A Namespace can be added as follows.

Arguments

Argument

Description

NAMESPACE | The new Namespace.

Example

$ nitropy nethsm --host $NETHSM_HOST add-namespace ns1
Namespace ns1 added to NetHSM localhost:8443

Delete Namespace#

Delete a Namespace from the NetHSM.

Deleting a Namespace also deletes all keys of that Namespace. Remaining users in the Namespace cannot add keys until the Namespace has been added again.

A Namespace can be deleted as follows.

Arguments

Argument

Description

NAMESPACE

The Namespace to delete.

Example

$ nitropy nethsm --host $NETHSM_HOST delete-namespace ns1
Namespace ns1 deleted on NetHSM localhost:8443

Tags for Users#

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 user accounts with the Operator role only. The Operators can see all keys, but only use those with at least one corresponding Tag. A key can not be modified by an Operator user.

To learn about how to use Tags on keys, please refer to Tags for Keys.

A Tag can be added as follows.

Arguments

Argument

Description

USER_ID

The user ID to set the tag on.

TAG

The tag to set on the user ID.

Example

nitropy nethsm --host $NETHSM_HOST add-operator-tag operator1 berlin
Added tag berlin for user operator1 on the NetHSM localhost:8443

The Tag can be deleted as follows.

Arguments

Argument

Description

USER_ID

The user ID to set the tag on.

TAG

The tag to set on the user ID.

Example

nitropy nethsm --host $NETHSM_HOST delete-operator-tag operator1 berlin
Deleted tag berlin for user operator1 on the NetHSM localhost:8443