行政部门¶

本章介绍*Administrator* 角色用户的管理任务。请参阅`角色<administration#roles>`__ 章，了解有关该角色的更多信息。

重要

请确保你在开始工作前阅读`本文件<index.html>`__开头的信息。

系统管理¶

设备信息¶

可以按以下方式检索NetHSM的供应商和产品信息。

例子

$ nitropy nethsm --host $NETHSM_HOST info

Host:    localhost:8443
Vendor:  Nitrokey GmbH
Product: NetHSM

启动模式¶

NetHSM可以在*Attended Boot*模式和*Unattended Boot*模式下使用。

启动模式	描述
参加的培训	NetHSM启动后进入_锁定_状态。解锁密码，在每次启动时都需要输入密码，用来解密用户数据。出于安全考虑，推荐使用这种模式，它是新配置的系统的默认模式。
无人值守的启动	系统在无人值守的情况下启动，不需要输入解锁密码进入_运行_状态。如果你的可用性要求不能用亲自启动模式来满足，就使用这种模式。

警告

无论启动模式如何，解锁密码 ，都会保留其有效性，并且在其他硬件上恢复备份时需要。在任何时候都要保证*解锁密码* 的安全。

当前的启动模式可以按以下方式检索。

例子

$ nitropy nethsm --host $NETHSM_HOST get-config --unattended-boot

Configuration for NetHSM localhost:8443:
   Unattended boot: off

启动模式可以按以下方式改变。在下次启动时，NetHSM会有相应的表现。

论点

争论	描述
状况	启用或禁用无人值守启动。可以有``on`或``off``的值。

例子

$ nitropy nethsm --host $NETHSM_HOST set-unattended-boot on

Updated the unattended boot configuration for NetHSM localhost:8443

国家¶

NetHSM软件有四种状态。未配置，配置，锁定*和*运行。

国家	描述
未分配	无配置的NetHSM（出厂默认）。
规定的。	有配置的NetHSM。配置的状态意味着运行或锁定的状态。
操作性	NetHSM具有配置并准备执行命令。运行的状态意味着配置*的状态。
被锁住	有配置的NetHSM，但数据存储被加密且无法访问。通常情况下，下一步是解锁系统。锁定的状态意味着配置的状态。

NetHSM的当前状态可以按以下方式检索。

例子

$ nitropy nethsm --host $NETHSM_HOST state

NetHSM localhost:8443 is Unprovisioned

新的 NetHSM 处于*未配置* 状态，配置后进入*运行* 状态。`Provisioning<getting-started#provisioning>`__ 章节介绍了 NetHSM 的配置。

一个处于*运行*状态的NetHSM可以再次被锁定，以保护它，方法如下。

例子

$ nitropy nethsm --host $NETHSM_HOST lock

NetHSM localhost:8443 locked

处于*锁定* 状态的NetHSM可以按以下方式解锁。当NetHSM处于_Locked_状态时，不可能有其他操作。之后，NetHSM处于_Operational_状态。

例子

$ nitropy nethsm --host $NETHSM_HOST unlock

NetHSM localhost:8443 unlocked

解锁密码¶

如果NetHSM处于*Locked*状态，Unlock Passphrase*将用于获得*Unlock Key。密码口令最初是在NetHSM的供应期间设置的。

警告

在不知道当前值的情况下，无法重置解锁密码。如果解锁密码丢失，既无法重置为新值，也无法解锁 NetHSM。

解锁密码*可按以下方式设置。

可选择的选项

选项	描述
-n`, ` ` ` ``--new-passphrase` TEXT	新的解锁口令
-p`, ` ` ` ``--current-passphrase` TEXT	当前的解锁密码
`-f`,``--force``	更改密码前不要要求确认

例子

$ 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证书¶

TLS证书用于基于HTTPS的REST API，因此也被*nitropy*使用。在配置过程中，会创建一个自签名的证书。该证书可以被替换，例如，用一个来自证书机构（CA）的签名证书。在这种情况下，必须生成一个证书签名请求（CSR）。签署后的证书必须导入到NetHSM中。

只有在更换证书时才有必要进行更改。这种改变可能是用一个来自证书颁发机构（CA）的签名证书来取代它。

TLS证书可以按以下方式检索。

必要的选项

选项	描述
-a`, ``--api.	Get the certificate for the NetHSM TLS interface

例子

$ nitropy nethsm --host $NETHSM_HOST get-certificate --api

TLS证书可以按以下方式生成。

必要的选项

选项	描述
-t`, ``--type` [RSA\|Curve25519\|EC_P224\|EC_P256\|EC_P384\|EC_P521]`。	生成密钥的类型
-l`, ``--length` INTEGER`。	生成的密钥的长度

例子

$ nitropy nethsm --host $NETHSM_HOST generate-tls-key -t Curve25519

Key for TLS interface generated on NetHSM localhost:8443

证书的证书签名请求（CSR）可按以下方式生成。

必要的选项

选项	描述
-a`, ``--api.	为NetHSM TLS证书生成一个CSR
--country`````TEXT`	国家名称
--state-or-province`````TEXT`	州或省的名称
--locality`````TEXT`	地点名称
--organization`````TEXT`	组织名称
--organizational-unit`````TEXT`	组织单位名称
--common-name`````TEXT``	俗称
--email-address`````TEXT`	电子邮件地址

例子

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

该证书可以按以下方式更换。

必要的选项

选项	描述
-a`, ``--api.	为NetHSM TLS接口设置证书

论点

争论	描述
`FILENAME`	证书文件

例子

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

网络¶

网络配置定义了用于*网络端口*的设置。

备注

此设置不配置*BMC网络端口*。

网络配置可以按以下方式检索。

必要的选项

选项	描述
`--network`	查询网络配置

例子

$ 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

设置网络配置如下。

备注

NetHSM不支持DHCP（动态主机配置协议）。

备注

NetHSM不支持IPv6（互联网协议版本6）。

必要的选项

选项	描述
-a`, ``--ip-address.	新的IP地址
`-n`, `--netmask`.	新的网络掩码
`-n`, `--netmask`.	新的网关

例子

$ 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

时间¶

时间配置设置NetHSM软件的系统时间。通常不需要设置系统时间，因为它是在配置期间设置的。

时间配置可以按以下方式检索。

必要的选项

选项	描述
`--time`	查询系统时间

例子

$ nitropy nethsm -host $NETHSM_HOST get-config --time

Configuration for NetHSM localhost:8443:
Time:            2022-08-17 11:40:00+00:00

设置NetHSM的时间。

重要

请确保以UTC时区传递时间。

论点

争论	描述
`time`	要设置的系统时间（格式：YYY-MM-DDTHH:MM:SSZ）。

例子

$ nitropy nethsm -h $NETHSM_HOST set-time 2022-08-17T11:40:00Z

Updated the system time for NetHSM localhost:8443

度量衡¶

NetHSM 记录系统参数的度量。请参阅`Metrics<metrics>`__了解每个指标的更多信息。

这些指标可以按以下方式检索。

需要的角色

此操作需要使用*Metrics* 角色进行验证。

例子

$ 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

伐木¶

NetHSM可以将系统事件记录到串行端口或网络上的syslog服务器上。

重要

对于任何生产部署，应持续监测NetHSM日志，以提供任何潜在安全问题的即时通知。

系统日志服务器的配置可以按以下方式检索。

必要的选项

选项	描述
`--network`	查询日志配置

例子

$ nitropy nethsm -h $NETHSM_HOST get-config --logging

Logging:
   IP address:    0.0.0.0
   Port:          514
   Log level:     info

系统日志服务器的配置可按以下方式设置。

必要的选项

选项	描述
-p`, ``--passphrase` TEXT`。	新记录目的地的IP地址
-p`, ``--port` INTEGER`。	新记录目的地的端口
-l`, ``--log-level` [debug\|info\|warning\|error]`。	新的日志级别

例子

$ 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

串行控制台从NetHSM的硬件开始工作。它包括来自NetHSM固件和NetHSM软件的事件。

串行控制台连接设置如下。

设置	价值
波特率	115200
数据位	8
停止位	1
偶数	无
流量控制	无

备份¶

NetHSM的*用户数据*可以被保存到一个备份文件中。这个备份文件包含所有的*用户数据*，即*配置存储*，认证存储，域名密钥存储*和*密钥存储。

重要

如果在不同的 NetHSM 硬件上还原*Unattended Boot* 模式下的 NetHSM 系统软件，则需要*Unlock Passphrase* 。请参阅`解锁密码<administration#unlock-passphrase>`__一章了解更多信息。

重要

处于*无人值守启动*模式的NetHSM在恢复后将处于同一模式。

在开始备份之前，必须设置*备份密码*。备份密码*是用来对备份文件中的数据进行加密的。

警告

在不知道当前值的情况下，无法重置备份口令。如果备份口令丢失，既不能重置为新值，也不能恢复已创建的备份。

备份口令可按以下方式设置。

可选择的选项

选项	描述
-n`, ` ` ` ``--new-passphrase` TEXT	新的备份口令
-p`, ` ` ` ``--current-passphrase` TEXT	当前备份口令（如果未设置，则为空字符串）
`-f`,``--force``	更改密码前不要要求确认

例子

$ 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

备份可以按以下方式执行。

需要的角色

此操作需要使用*Backup* 角色进行身份验证。

论点

争论	描述
`FILENAME`	备份文件

例子

$ nitropy nethsm -h $NETHSM_HOST backup /tmp/nethsm-backup

Backup for localhost:8443 written to /tmp/backup

恢复¶

NetHSM可以从一个备份文件中恢复。

如果NetHSM是*Unprovisioned* ，它将恢复所有*用户数据* ，包括系统配置和重新启动。因此，之后系统可能会得到不同的网络设置、TLS证书和*解锁密码* 。
如果NetHSM是*Provisioned* ，它将恢复用户和用户钥匙，但不恢复系统配置。在这种情况下，所有以前存在的用户和用户钥匙将被删除。NetHSM结束时处于*Operational* 状态。

可以按以下方式进行恢复。

可选择的选项

选项	描述
-p`, ``--backup-passphrase` passphrase`。	备份口令*
-t`, ``--system-time.	要设置的系统时间（格式：`YYYY-MM-DDTHH:MM:SSZ`)

重要

请确保你的本地电脑的时间设置正确。要设置不同的时间，请手动提供。

论点

争论		描述
`FILENAME` \| 恢复文件

例子

$ nitropy nethsm -h $NETHSM_HOST restore /tmp/nethsm-backup

Backup passphrase:
Backup restored on NetHSM localhost:8443

Replication¶

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. The synchronization can be easily scripted by using pynitrokey as shown in this example. This separate system doesn’t have access to the backed up data in clear text because the backup files are encrypted twice. The separate system is in possession of the backup passphrase only but not of the Domain Key resp. Unlock Passphrase which is the second layer of encryption. See the system design for further details.

软件更新¶

软件更新可分两步安装。首先，需要将更新镜像上传到*Provisioned* NetHSM。NetHSM 会验证镜像的真实性、完整性和版本号。如果有发行说明，NetHSM 还会显示。

警告

由于安装了一个测试版的更新，可能会发生数据丢失!稳定的版本应该不会导致数据丢失。然而，建议在更新前创建一个备份。

更新文件可以按以下方式上传。

论点

争论	描述
`FILENAME`	更新文件

例子

$ nitropy nethsm --host $NETHSM_HOST update /tmp/nethsm-update.img.bin

Image /tmp/nethsm-update.img.bin uploaded to NetHSM localhost:8443

之后，可以应用或中止更新。请参考下面所需的选项。如果NetHSM在 "提交 "操作前断电，更新文件必须重新上传。

重要

如果上传更新图像失败，显示``Error: NetHSM request failed: Bad request -- malformed image``，请按照以下步骤操作。

根据提供的签名进行检查，确保更新文件有效。
确保没有启用高日志级别，如``DEBUG``。请参阅`Logging<https://docs.nitrokey.com/nethsm/administration#logging>`__ 一章，了解有关日志级别配置的更多信息。
重启设备，释放已用内存。

更新可按以下方式应用（提交）。只有在* NetHSM 成功启动新的系统软件版本后，才会执行任何数据迁移*。

例子

$ nitropy nethsm --host $NETHSM_HOST commit-update

Update successfully committed on NetHSM localhost:8443

可以按以下方式取消更新。

例子

$ nitropy nethsm --host $NETHSM_HOST cancel-update

Update successfully cancelled on NetHSM localhost:8443

系统信息¶

固件版本、软件版本和硬件版本等系统信息可按如下方式检索。

例子

$ 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

重新启动和关机¶

NetHSM可以远程重启和关机，也可以通过NetHSM硬件前面的重启和关机按钮来实现。

远程重启可以按以下方式启动。

例子

$ 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

可以通过以下方式启动远程关机。

例子

$ 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

重置为出厂默认值¶

供给的 NetHSM可以被重置为出厂默认值。在这种情况下，所有的用户数据都被安全删除，NetHSM启动后进入*未配置的* 状态。之后，你可能想`，为NetHSM提供<getting-started#provisioning>`__。

重置为出厂默认值可以按以下方式进行。

例子

$ 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

用户管理¶

角色¶

NetHSM允许通过使用不同的角色来分担职责。在NetHSM上配置的每个用户账户都有以下一个*角色*分配给它。

角色	描述
管理人	拥有此角色的用户账户可以访问NetHSM提供的所有操作，但密钥使用操作除外，即消息签名和解密。
操作者	拥有此角色的用户账户可以访问所有的钥匙使用操作，只读的钥匙管理操作子集和用户管理操作，只允许对他们自己的账户进行更改。
指标	拥有此角色的用户账户只能访问只读的度量衡操作。
备份	拥有该角色的用户账户只能访问启动系统备份所需的操作。

有关更精细的访问限制，请参阅`命名空间<administration#namespaces>`__ 和`标记<administration#tags-for-users>`__ 。

备注

在未来的版本中，可能会引入额外的*角色*。

添加用户¶

向 NetHSM 添加用户账户。每个用户账户都有一个*角色* ，需要指定该角色。请参阅`角色<administration#roles>`__ 一章，了解有关*角色* 的更多信息。

可选择将用户分配到`*命名空间*<administration#namespaces>`__。

备注

用户 ID 必须是字母数字。如果没有指定用户 ID，NetHSM 将随机分配一个用户 ID。

可以按以下方式添加一个用户账户。

必要的选项

选项	描述
-n`, ``--real-name` TEXT`。	新用户的真实姓名
-N`, ` ` ` ``--namespace` TEXT	新用户的命名空间
-r`, ``--role` [Administrator\|Operator\|Metrics\|Backup]`。	新用户的*角色
-p`, ``--passphrase` TEXT`。	新用户的口令

可选择的选项

选项	描述
-u`, ``--user-id` TEXT`。	新用户的用户ID

例子

$ 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

默认情况下，命名空间由添加新用户的用户继承。只有没有名称空间的用户才能为新用户选择不同的名称空间。命名空间用作用户名的前缀，例如 namespace~user。因此，同一个用户名可以在多个命名空间中使用。

删除用户¶

从NetHSM中删除一个用户账户。

警告

删除是永久性的，不能被恢复。

可以按以下方式删除一个用户账户。

论点

争论	描述
`USER_ID`	用户身份。

例子

$ nitropy nethsm --host $NETHSM_HOST delete-user operator1

User operator1 deleted on NetHSM localhost:8443

列表中的用户¶

列出NetHSM上的用户。

该清单可以按以下方式检索。

可选择的选项

选项	描述
`--details`, `--no-details`.	查询用户的真实姓名和角色

例子

$ nitropy nethsm --host $NETHSM_HOST list-users

Users on NetHSM localhost:8843:

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

名称空间内的用户只能看到同一名称空间内的用户。

用户密码¶

用户账户的口令可以被重置。密码锁是在添加用户账户时初始设置的。

备注

密码锁必须有>=10和<=200个字符。

用户口令可按以下方式设置。

必要的选项

选项	描述
-u`, ``--user-id` TEXT`。	用户的用户ID
-p`, ``--passphrase` TEXT`。	用户的新密码

例子

$ nitropy nethsm --host $NETHSM_HOST set-passphrase --user-id operator1

Passphrase:
Repeat for confirmation:
Updated the passphrase for user operator1 on NetHSM localhost:8443

命名空间¶

命名空间 是在软件 2.0 版本中引入的。从软件的早期版本迁移时，所有现有用户和密钥都将没有命名空间。

与分区的概念类似，NetHSM 支持更灵活的*Namespaces* ，可将 NetHSM 上的密钥、管理员和用户分成不同的子集。用户只能查看和使用同一命名空间中的密钥，也只能查看同一命名空间中的用户。无法查看其他命名空间的用户，也无法查看和使用其他命名空间的密钥。创建新用户时，新用户将继承创建用户的名称空间。所有命名空间共享可用存储容量。

具有*管理员* `角色<administration#roles>`__ 的用户，如果不在名称空间中，也称为*R-Administrator* ；如果在名称空间中，则称为*N-Administrator* 。

特殊规则适用于*R-Administrator* 用户：他们可以为新用户设置命名空间、列出所有用户和查询某个用户的命名空间。此外，NetHSM 配置只能由*R-Administrator* 用户访问。 R 管理员不能查看名称空间中的键。

要在名称空间中生成密钥和用户，必须由*R-Administrator* 用户创建名称空间。一旦创建了命名空间，R-Administrator 用户就不能再创建、删除或修改该命名空间中的用户。这样可以保护 R-Administrator 访问名称空间的密钥（也可以通过代表添加新用户或重置现有用户或管理员的凭据来间接保护）。因此，在创建命名空间之前，有必要为命名空间创建*N-Administrator* 用户。R-Administrator 用户也可以删除名称空间和其中包含的所有密钥。

列出命名空间¶

列出 NetHSM 上的命名空间。

该清单可以按以下方式检索。

例子

$ nitropy nethsm --host $NETHSM_HOST list-namespaces

Namespaces on NetHSM localhost:8843:
- ns1
- ns2

添加命名空间¶

向 NetHSM 添加命名空间。

R-Administrator 用户可以在命名空间创建新账户。创建后，只有*N-Administrator* 用户可以管理名称空间中的用户。只有在添加名称空间后，才能在名称空间中创建和使用密钥。

备注

命名空间 ID 必须是字母数字。如果没有指定用户 ID，NetHSM 会随机分配一个。

命名空间的添加方法如下。

论点

争论		描述
`NAMESPACE` \| 新命名空间。

例子

$ nitropy nethsm --host $NETHSM_HOST add-namespace ns1

Namespace ns1 added to NetHSM localhost:8443

删除命名空间¶

从 NetHSM 中删除命名空间。

删除名称空间也会删除该名称空间的所有键。名称空间中的其他用户在再次添加名称空间之前无法添加键值。

删除命名空间的方法如下。

论点

争论	描述
`NAMESPACE`	要删除的命名空间。

例子

$ nitropy nethsm --host $NETHSM_HOST delete-namespace ns1

Namespace ns1 deleted on NetHSM localhost:8443

用户的标签¶

标签，可用于对钥匙设置细粒度的访问限制，是一项可选功能。一个或多个*标签* 只能分配给具有*操作员* 角色的用户账户。操作员 可以看到所有的键，但只能使用那些至少有一个相应的*标签* 。一个键不能被一个*操作员* 用户修改。

要了解如何在钥匙上使用*标签* ，请参阅`钥匙标签<operation#tags-for-keys>`__。

标签，可按以下方式添加。

论点

争论	描述
`USER_ID`	要设置标签的用户ID。
`TAG`	要在用户ID上设置的标签。

例子

nitropy nethsm --host $NETHSM_HOST add-operator-tag operator1 berlin

Added tag berlin for user operator1 on the NetHSM localhost:8443

可以按以下方式删除*标签。

论点

争论	描述
`USER_ID`	要设置标签的用户ID。
`TAG`	要在用户ID上设置的标签。

例子

nitropy nethsm --host $NETHSM_HOST delete-operator-tag operator1 berlin

Deleted tag berlin for user operator1 on the NetHSM localhost:8443