Integração#

O capítulo descreve processos para várias tarefas e dirige-se a todos os grupos de utilizadores.

REST-API#

NetHSM’s primary interface is a modern REST-API that guarantees best performance and functionality. The API specification is available in OpenAPI format, and can be inspected and tested in the API browser.

PKCS#11#

The NetHSM supports the PKCS#11 standard. The required driver is available from the repository. The repository containes the source code and libraries, for different operating systems. The PKCS#11 guide describes the usage in detail.

Desenvolvimento e testes#

Demo Instance#

A public NetHSM demo instance is available at nethsmdemo.nitrokey.com. It will be reset every eight hours (CET 6:00, 14:00, 22:00). User «admin», password «adminadmin», unlock password «unlockunlock».

Container Image#

The container image is distributed as an OCI image and can be obtained from Docker Hub. It can be run locally with a compatible executor, e.g. Docker or Podman.

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

  • network configuration

  • factory reset

  • reboot

  • software update

The container can be executed as follows.

$ sudo docker run --rm -ti -p8443:8443 nitrokey/nethsm:testing

This will run NetHSM as a Unix process inside the container and expose the REST API on the port 8443 via the HTTPS protocol.

Additionaly to running the NetHSM as a Unix process it can be run as a unikernel supported by KVM.

The container can be executed as follows.

$ docker run -ti --rm -p 8443:8443 --device /dev/net/tun --device /dev/kvm --cap-add=NET_ADMIN nitrokey/nethsm:testing

This will run NetHSM as a unikernel inside a KVM virtual machine. The container will expose the REST API, via the HTTPS protocol, on the interface tap200 with the IP address 192.168.1.100 and port 8443.

Importante

The container uses a self-signed TLS certificate. Make sure to use the correct connection settings to establish a connection. Please refer to chapter NetHSM introduction to learn more.

Integration Into Custom Application#

To integrate the NetHSM into own custom applications, client libraries are available for almost all programming languages. Here are libraries for Python and Rust as well as this 3rd party Rust crate. For all other programming languages we recommend using OpenAPI Generator.

A lista de todas as línguas disponíveis pode ser recuperada da seguinte forma.

$ docker run --rm -ti openapitools/openapi-generator-cli list -i stable

O cliente NetHSM pode ser gerado para a sua linguagem de programação como se segue.

$ docker run --rm -ti -v "${PWD}/out:/out" openapitools/openapi-generator-cli generate -i=https://nethsmdemo.nitrokey.com/api_docs/nethsm-api.yaml -o out -g javascript

O código do cliente gerado, neste exemplo JavaScript, será criado no diretório ./out/. Esta pasta também contém a documentação necessária para a sua utilização.

Importante

If Podman is used with enforcing SELinux, a labeling to the volume mount might be required. The mode of SELinux can be requested with sestatus |grep "Current mode". If the mode is set to enforcing, a change to the context is required. In this case the volume mount must be postfixed with :z, resulting in -v "${PWD}/out:/out:z".

Command-line interface#

Users may administrate and use a NetHSM using a dedicated command-line interface (CLI). Nitrokey offers nitropy, which is distributed in the Python based pynitrokey. With nethsm an alternative third-party application exists, which is developed in the Rust crate nethsm-cli.