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
Information about the /info endpoint can be found in the API documentation.
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
Information about the /config/unattended-boot endpoint can be found in the API documentation.
The boot mode can be changed as follows.
Arguments
Argument |
Description |
---|---|
Status |
Enable or disable Unattended Boot.
Can have value |
Example
$ nitropy nethsm --host $NETHSM_HOST set-unattended-boot on
Updated the unattended boot configuration for NetHSM localhost:8443
Information about the /config/unattended-boot endpoint can be found in the API documentation.
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#
The current state of the NetHSM can be retrieved as follows.
Example
$ nitropy nethsm --host $NETHSM_HOST state
NetHSM localhost:8443 is Unprovisioned
Information about the /health/state endpoint can be found in the API documentation.
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
Information about the /lock endpoint can be found in the API documentation.
A NetHSM in Locked state can be unlocked as follows.
Example
$ nitropy nethsm --host $NETHSM_HOST unlock
NetHSM localhost:8443 unlocked
Information about the /unlock endpoint can be found in the API documentation.
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 |
---|---|
|
The new unlock passphrase |
Example
$ nitropy nethsm --host $NETHSM_HOST set-unlock-passphrase
Passphrase:
Repeat for confirmation:
Updated the unlock passphrase for localhost:8443
Information about the /config/unlock-passphrase endpoint can be found in the API documentation.
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 |
---|---|
|
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-----
Information about the /config/tls/cert.pem endpoint can be found in the API documentation.
The TLS certificate can be generated as follows.
Required Options
Option |
Description |
---|---|
|
The type for the generated key |
|
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
Information about the /config/tls/generate endpoint can be found in the API documentation.
The Certificate Signing Request (CSR) for the certificate can be generated as follows.
Required Options
Option |
Description |
---|---|
|
Generate a CSR for the NetHSM TLS certificate |
|
The country name |
|
The state or province name |
|
The locality name |
|
The organization name |
|
The organization unit name |
|
The common name |
|
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-----
Information about the /config/tls/csr.pem endpoint can be found in the API documentation.
The certificate can be replaced as follows.
Required Options
Option |
Description |
---|---|
|
Set the certificate for the NetHSM TLS interface |
Arguments
Argument |
Description |
---|---|
|
Certificate file |
Example
nitropy nethsm --host $NETHSM_HOST set-certificate --api /tmp/nethsm-certificate
Information about the /config/tls/csr.pem endpoint can be found in the API documentation.
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 |
---|---|
|
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
Information about the /config/network endpoint can be found in the API documentation.
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 |
---|---|
|
The new IP address |
|
The new netmask |
|
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
Information about the /config/network endpoint can be found in the API documentation.
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 |
---|---|
|
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
Information about the /config/time endpoint can be found in the API documentation.
Set the time of the NetHSM.
Important
Make sure to pass the time in UTC timezone.
Arguments
Argument |
Description |
---|---|
|
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
Information about the /config/time endpoint can be found in the API documentation.
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
Information about the /metrics endpoint can be found in the API documentation.
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 |
---|---|
|
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
Information about the /config/logging endpoint can be found in the API documentation.
The syslog server configuration can be set as follows.
Required Options
Option |
Description |
---|---|
|
The IP address of the new logging destination |
|
The port of the new logging destination |
|
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
Information about the /config/logging endpoint can be found in the API documentation.
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 |
---|---|
|
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
Information about the /config/backup-passphrase endpoint can be found in the API documentation.
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 |
---|---|
|
Backup file |
Example
$ nitropy nethsm -h $NETHSM_HOST backup /tmp/nethsm-backup
Backup for localhost:8443 written to /tmp/backup
Information about the /system/backup endpoint can be found in the API documentation.
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 |
---|---|
|
The Backup Passphrase |
|
The system time to set (Format: |
Important
Make sure the time of your local computer is correctly set. To set a different time, please provide it manually.
Arguments
Argument |
Description |
|
---|---|---|
|
Example
$ nitropy nethsm -h $NETHSM_HOST restore /tmp/nethsm-backup
Backup passphrase:
Backup restored on NetHSM localhost:8443
Information about the /system/restore endpoint can be found in the API documentation.
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 |
---|---|
|
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
Information about the /system/update endpoint can be found in the API documentation.
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
Information about the /system/commit-update endpoint can be found in the API documentation.
The update can be cancelled as follows.
Example
$ nitropy nethsm --host $NETHSM_HOST cancel-update
Update successfully cancelled on NetHSM localhost:8443
Information about the /system/cancel-update endpoint can be found in the API documentation.
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
Information about the /system/reboot endpoint can be found in the API documentation.
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
Information about the /system/shutdown endpoint can be found in the API documentation.
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 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
Information about the /system/factory-reset endpoint can be found in the API documentation.
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 |
---|---|
|
The real name of the user |
|
The Role of the new user |
|
The passphrase of the new user |
Optional Options
Option |
Description |
---|---|
|
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
Information about the /users endpoint, to create a user without specifying the user ID, can be found in the API documentation.
Information about the /users/{UserID} endpoint, to create a user with specifying the user ID, can be found in the API documentation.
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 |
---|---|
|
The user Id of the user. |
Example
$ nitropy nethsm --host $NETHSM_HOST delete-user operator1
User operator1 deleted on NetHSM localhost:8443
Information about the /users/{UserID} endpoint can be found in the API documentation.
List Users#
List the users on the NetHSM.
The list can be retrieved as follows.
Optional Options
Option |
Description |
---|---|
|
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
Information about the /users endpoint can be found in the API documentation.
Information about the /users/{UserID} endpoint can be found in the API documentation.
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 |
---|---|
|
The user ID of the user |
|
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
Information about the /users/{UserID}/passphrase endpoint can be found in the API documentation.