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 Unlock Passphrase needs to be entered during each start, which is used to decrypt the User Data. For security reasons, this mode is recommended.

Unattended Boot

No Unlock Passphrase is required, therefore the NetHSM can start unattended. Use this mode if your availability requirements can not be fulfilled with Attended Boot mode.

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.

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 protected (requires unlock). The Operational 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.

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.

The Unlock Passphrase can be set as follows.

Optional Options

Option

Description

-p, --passphrase TEXT

The new unlock passphrase

Example

$ nitropy nethsm --host $NETHSM_HOST set-unlock-passphrase
Passphrase:
Repeat for confirmation:
Updated the unlock passphrase for 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.

Note

This command requires the authentication of a user with the Metrics role. Please refer to chapter Roles to learn more about the role.

The metrics can be retrieved as follows.

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.

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

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

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.

The backup passphrase can be set as follows.

Optional Options

Option

Description

-p, --passphrase TEXT

The new backup passphrase

Example

$ nitropy nethsm -h $NETHSM_HOST -u admin set-backup-passphrase
Passphrase:
Repeat for confirmation:
Updated the backup passphrase for NetHSM localhost:8443

Note

This command requires the authentication of a user with the Backup role. Please refer to chapter Roles to learn more.

The backup can be executed as follows.

Arguments

Argument

Description

FILENAME

Backup file

Example

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

Note

This backup file can be restored on an unprovisioned NetHSM instance only.

Restore#

The NetHSM can be restored from a backup file.

Note

The NetHSM must be in an Unprovisioned 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

Update#

Updates for the NetHSM can be installed in a two-step process. First the update image needs to be uploaded to the NetHSM. The image is checked and validated automatically.

Warning

Data loss may occur due to the installation of a beta update!

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.cpio
Image /tmp/nethsm-update.img.cpio uploaded to NetHSM localhost:8443

Afterwards the update can be applied or aborted. Please refer to the desired option below.

The update can be applied (committed) as follows.

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

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 is about to reboot

The remote shutdown can be initiated as follows.

Example

$ nitropy nethsm --host $NETHSM_HOST shutdown
NetHSM localhost:8443 is about to shutdown

Reset to Factory Defaults#

The NetHSM can be reset to factory defaults. During this process all user data gets deleted.

The reset to factory defaults can be performed as follows.

Example

$ nitropy nethsm -h $NETHSM_HOST factory-reset
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.

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.

Note

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

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

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

Tags for Users#

Tags can be used to set access restrictions on keys, and are an optional feature. They can only be assigned to user accounts with the Operator role. 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.

The 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