Crate nethsm

source ·
Expand description

A high-level library to interact with the API of a Nitrokey NetHSM

Provides high-level integration with a Nitrokey NetHSM and official container. As this crate is a wrapper around nethsm_sdk_rs it covers all available actions from provisioning, over key and user management to backup and restore.

The NetHSM provides dedicated user management based on several roles (see UserRole) which can be used to separate concerns.

The cryptographic key material on the device can be assigned to one or several tags. Users in the “operator” role can be assigned to the same tags to gain access to the keys.

Apart from the crate specific documentation it is very recommended to read the canonical upstream documentation as well: https://docs.nitrokey.com/nethsm/

This crate re-exports the following nethsm_sdk_rs types so that the crate does not have to be relied on directly:

Using the NetHsm struct it is possible to establish a TLS connection for multiple users. TLS validation can be configured based on a variant of the ConnectionSecurity enum:

§Examples

use nethsm::{ConnectionSecurity, Error, NetHsm};

// Create a new connection to a NetHSM at "https://example.org" using admin credentials
let nethsm = NetHsm::new(
    "https://example.org/api/v1".try_into()?,
    ConnectionSecurity::Unsafe,
    Some(("admin".to_string(), Some("passphrase".to_string()))),
    None,
    None,
)?;

// Connections can be initialized without any credentials and more than one can be provided later on
let nethsm = NetHsm::new(
    "https://example.org/api/v1".try_into()?,
    ConnectionSecurity::Unsafe,
    None,
    None,
    None,
)?;

nethsm.add_credentials(("admin".to_string(), Some("passphrase".to_string())));
nethsm.add_credentials(("user1".to_string(), Some("other_passphrase".to_string())));

// A set of credentials must be used before establishing a connection with the configured NetHSM
nethsm.use_credentials("user1")?;

Structs§

Enums§