Integration¶

The chapter describes processes for various tasks and aims at all user groups.

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.

Development and Testing¶

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¶

NetHSM container images are available for testing and production.

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.

The list of all available languages can be retrieved as follows.

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

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

The NetHSM client can be generated for your programming language as follows.

$ 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

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

The generated client code, in this example JavaScript, will be created in the ./out/ directory. This folder also contains the necessary documentation how to use it.

Important

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.