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 the 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 a role system (see UserRole) which can be used to separate concerns. Each user has exactly one role.

With the help of a namespace concept, it is possible to segregate users and their keys into secluded groups. Notably, this introduces R-Administrators (system-wide users in the Administrator role), which have access to all system-wide actions, but can not modify users and keys in a namespace and N-Administrators (namespace users in the Administrator role), which have access only to actions towards users and keys in their own namespace. Namespace users in the Operator role only have access to keys in their own namespace, while system-wide users only have access to system-wide keys.

The cryptographic key material on the NetHSM 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 respective keys.

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

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

§Reexports

This crate re-exports the following [nethsm_sdk_rs] types, so that the crate does not have to be relied upon directly:

§Examples

use nethsm::{ConnectionSecurity, Credentials, NetHsm, Passphrase};

// 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(Credentials::new("admin".parse()?, Some(Passphrase::new("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(Credentials::new("admin".parse()?, Some(Passphrase::new("passphrase".to_string()))));
nethsm.add_credentials(Credentials::new("user1".parse()?, Some(Passphrase::new("other_passphrase".to_string()))));

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

Modules§

  • key 🔒
  • nethsm_sdk 🔒
  • openpgp 🔒
    OpenPGP-related functions.
  • tls 🔒
  • user 🔒
    Module for credentials, user IDs and passphrases.

Structs§

Enums§

Constants§

Functions§