Production Image#

The production image is provided for production environments with high security demands. It requires an external etcd key-value store which is connected through an encrypted connection. The NetHSM process can be executed with hardware-based separation (KVM) and device-specific encryption. The image is distributed as OCI image and can be run locally with a compatible executor such as Docker and Podman.

Σε σύγκριση με το υλικό NetHSM, οι ακόλουθες λειτουργίες δεν υλοποιούνται στο REST API του εμπορευματοκιβωτίου λογισμικού:

  • Network configuration

  • Factory reset

  • Reboot

  • Software update

The NetHSM production container is a product for paying customers only and can be purchased here. The image can be obtained from Nitrokey NetHSM registry using the credentials provided after purchase.

Προειδοποίηση

The security of the NetHSM software container strongly depends on the platform’s security. A compromised platform could easily compromise a NetHSM software container it executes. In addition the TRNG is not existent so that the entropy used and provided by the NetHSM depends on the platform’s entropy.

Tagging Policy#

The images in the repository are tagged with the Git commit hash and the version of the release. The latest image is tagged with latest.

Modes of Operation#

The image can be run in two modes of operation, i.e. Unix process or unikernel.

The Unix process mode runs NetHSM as a process on top of the operating system.

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 choose to run the container in the unikernel mode.

The mode can be set with the environment variable MODE (see next chapter Configuration).

Διαμόρφωση#

The container can be configured with the following environment variables.

Environment variable

Περιγραφή

DEBUG_LOG

Enables extended logging for NetHSM.

UNLOCKPW

A set unlock passphrase automatically unlocks the container during start.

MODE

The mode accepts the values unix or unikernel, defaults to unix.

ETCD_HOST

The URL/IP address of the host running the etcd service.

ETCD_PORT

The port running the etcd service, defaults to 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.

The container runtime secrets such as certificates and private keys need to be set with the secrets feature of Docker or Podman.

Secret variable

Περιγραφή

ca_cert

CA certificate which signed the client certificate and server certificate.

client_cert

Client certificate for authentication of the NetHSM process with the key-value store.

client_key

Client key for authentication of the NetHSM process with the key-value store.

server_cert

Server certificate for the API of the key-value store.

server_key

Server key for the API of the key-value store.

device_key

Device key of the NetHSM process. To learn more about the device key refer to chapter Terminology and Conventions in the system design.

Χρήση#

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#

You can obtain a provided compose file here. Make sure you have the necessary files for the secrets, mentioned in the compose file, available.

To run the container without the compose file you need to provide an external etcd yourself. Here you find the recommended container image for etcd. Make sure to pass the configuration options, as described in chapter Configuration.

Το δοχείο μπορεί να εκτελεστεί ως εξής.

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

Αυτό θα εκτελέσει το NetHSM ως διεργασία Unix μέσα στο δοχείο και θα εκθέσει το REST API στη θύρα «8443» μέσω του πρωτοκόλλου HTTPS.

Σημαντικό

Ο περιέκτης χρησιμοποιεί ένα αυτο-υπογεγραμμένο πιστοποιητικό TLS. Βεβαιωθείτε ότι χρησιμοποιείτε τις σωστές ρυθμίσεις σύνδεσης για να δημιουργήσετε μια σύνδεση. Ανατρέξτε στο κεφάλαιο Εισαγωγή στο NetHSM για να μάθετε περισσότερα.

Unikernel Mode#

You can obtain a provided compose file here. Make sure you have the necessary files for the secrets, mentioned in the compose file, available.

To run the container without the compose file you need to provide an external etcd yourself. Here you find the recommended container image for etcd. Make sure to pass the configuration options, as described in chapter 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

Αυτό θα εκτελέσει το NetHSM ως ένα unikernel μέσα σε μια εικονική μηχανή KVM. Το δοχείο θα εκθέσει το REST API, μέσω του πρωτοκόλλου HTTPS, στη διεπαφή tap200 με τη διεύθυνση IP 192.168.1.100 και τη θύρα 8443.

Σημαντικό

Ο περιέκτης χρησιμοποιεί ένα αυτο-υπογεγραμμένο πιστοποιητικό TLS. Βεβαιωθείτε ότι χρησιμοποιείτε τις σωστές ρυθμίσεις σύνδεσης για να δημιουργήσετε μια σύνδεση. Ανατρέξτε στο κεφάλαιο Εισαγωγή στο NetHSM για να μάθετε περισσότερα.