Production Image#

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

与 NetHSM 硬件相比,软件容器的 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 作为操作系统上的一个进程运行。

单内核模式在基于 KVM 的虚拟机中将 NetHSM 作为访客运行,与主机操作系统紧密分离。该模式仅适用于 Linux,需要访问``/dev/tun`` 和``/dev/kvm`` 设备节点以及``NET_ADMIN`` 能力。

重要

为了安全起见,选择在单内核模式下运行容器。

可通过环境变量``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 证书。

client_cert

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

client_key

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

server_cert

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

server_key

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

device_key

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

使用方法#

生产容器支持两种`运行模式<container.html#Modes of Operation>`__。下面几章将介绍如何使用提供的编译文件或 _run_ 命令运行容器。

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>`__一章,了解更多信息。