Production Image

生产镜像适用于安全性要求较高的生产环境。它需要通过加密连接的外部 etcd 键值存储。NetHSM 进程可通过基于硬件的分离(KVM)和特定设备加密来执行。该镜像以 OCI 镜像的形式发布,可通过兼容的执行器(如 Docker 和 Podman)在本地运行。

Compared to the NetHSM hardware the following functions are not implemented at the software container's REST API:

  • Network configuration

  • Factory reset

  • Reboot

  • Software update

NetHSM 生产容器是仅供付费客户使用的产品,可在`这里购买<https://www.nitrokey.com/contact>`__。可使用购买后提供的凭证从`硝基 NetHSM 注册表<https://registry.git.nitrokey.com/distribution/nethsm>`_ 获取镜像。

警告

NetHSM 软件容器的安全性在很大程度上取决于平台的安全性。被入侵的平台可以轻易入侵其执行的 NetHSM 软件容器。此外,TRNG 并不存在,因此 NetHSM 使用和提供的熵取决于平台的熵。

标记政策

版本库中的图片都标有 Git 提交哈希值和发布版本。最新的图像标记为``latest``。

Modes of Operation

该镜像可在两种运行模式下运行,即 Unix 进程或 unikernel。

  • Unix 进程模式将 NetHSM 作为操作系统上的一个进程运行。

  • The unikernel mode runs NetHSM as a guest in a KVM based virtual machine and provides strong separation from the host operating system. This mode is only available on Linux and requires access to the /dev/tun and /dev/kvm device nodes and the NET_ADMIN capability. For security reasons we recommend the unikernel mode.

可通过环境变量``MODE`` 设置模式(见下一章`配置<container.html#production-image-configuration>`__ )。

配置

The container can be configured with the following environment variables.

环境变量

描述

Ipsec(仅限 Linux)

启用 NetHSM 的扩展日志记录。

UNLOCKPW

设置的解锁口令会在启动过程中自动解锁容器。

MODE

模式可接受`unix`或`unikernel`,默认为`unix`。

ETCD_HOST

运行 etcd 服务的主机的 URL/IP 地址。

ETCD_PORT

运行 etcd 服务的端口,默认为 2379

ETCD_CA_CERT

The path to the certificate of the CA (Certificate Authority) which signed the client certificate.

ETCD_CLIENT_CERT

The path to the certificate for the client authentication.

ETCD_CLIENT_KEY

The path to the secret key for the client authentication.

容器运行时的机密(如证书和私钥)需要使用 Docker 或 Podman 的机密功能来设置。

秘密变量

描述

ca_cert

签署客户端证书和服务器证书的 CA 证书。

etcd_client_cert

客户端证书,用于通过键值存储对 NetHSM 进程进行身份验证。

etcd_client_key

客户端密钥,用于通过键值存储对 NetHSM 进程进行身份验证。

etcd_server_cert

键值存储 API 的服务器证书。

etcd_server_key

键值存储 API 的服务器密钥。

device_key

NetHSM 进程的设备密钥。要了解有关设备键的更多信息,请参阅`Terminology and Conventions<https://github.com/Nitrokey/nethsm/blob/main/docs/system-design.md#terminology-and-conventions>`__系统设计一章。

使用方法

The production container supports two modes of operation. The following chapters describe how to run the container with the provided compose files or with the run command.

Unix Mode

您可以从`获取所提供的编译文件<https://raw.githubusercontent.com/Nitrokey/nethsm/refs/heads/main/src/container/alpine/compose-unix.yaml>`__。请确保您已准备好编译文件中提到的机密所需的文件。

要在不使用编译文件的情况下运行容器,您需要自己提供一个外部 etcd。`在<https://quay.io/coreos/etcd>`___,你可以找到推荐的 etcd 容器镜像。请务必按照`Configuration<container.html#production-image-configuration>`__一章所述传递配置选项。

容器可以按以下方式执行。

$ docker run -ti --rm -p 8443:8443 registry.git.nitrokey.com/distribution/nethsm:latest

这将在容器内以 Unix 进程的形式运行 NetHSM,并通过 HTTPS 协议在端口 8443 上公开 REST API。

重要

容器使用一个自签的TLS证书。请确保使用正确的连接设置来建立连接。请参考`NetHSM介绍<index.html>`__一章,了解更多信息。

单内核模式

您可以从`获取所提供的编译文件<https://raw.githubusercontent.com/Nitrokey/nethsm/refs/heads/main/src/container/alpine/compose-unikernel.yaml>`__。请确保您已准备好编译文件中提到的机密所需的文件。

要在不使用编译文件的情况下运行容器,您需要自己提供一个外部 etcd。`在<https://quay.io/coreos/etcd>`___,你可以找到推荐的 etcd 容器镜像。请务必按照`Configuration<container.html#production-image-configuration>`__一章所述传递配置选项。

容器可以按以下方式执行。

$ docker run -ti --rm -p 8443:8443 --device /dev/net/tun --device /dev/kvm --cap-add=NET_ADMIN -e "MODE=unikernel" registry.git.nitrokey.com/distribution/nethsm:latest

这将在 KVM 虚拟机中以单内核方式运行 NetHSM。容器将通过 HTTPS 协议,在 IP 地址为 192.168.1.100、端口为 8443 的接口 "tap200 "上公开 REST API。

重要

容器使用一个自签的TLS证书。请确保使用正确的连接设置来建立连接。请参考`NetHSM介绍<index.html>`__一章,了解更多信息。