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 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
Information about the /config/unattended-boot endpoint can be found in the API documentation.
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 |
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 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#
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. 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
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.
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 |
|---|---|
|
The new unlock passphrase |
|
The current unlock passphrase |
|
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
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.
Please refer to Metrics to learn more about each metric.
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.
Important
For any production deployment, the NetHSM log should be monitored continuously to provide immediate notification of any potential security issues.
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.
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 |
|---|---|
|
The new backup passphrase |
|
The current backup passphrase (or an empty string if not set) |
|
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
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.
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 |
|---|---|
|
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.
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 |
|---|---|
|
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. If the NetHSM is powered down before the “commit” operation, the update file has to be uploaded again.
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
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#
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
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. |
See 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.
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.