Module test

Expand description

§NetHSM

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

The NetHSM is a hardware appliance, that serves as secure store for cryptographic keys. With the help of a REST API it is possible to communicate with the device (as well as the official nethsm container) for setup and various cryptographic actions.

The nethsm-sdk-rs library is auto-generated using openapi-generator. This leads to a broad API surface with sparse documentation, that this crate attempts to rectify with the help of a central struct used for authentication setup and communication.

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:

ConnectionSecurity::Unsafe: The host certificate is not validated.
ConnectionSecurity::Fingerprints: The host certificate is validated based on configurable fingerprints.
ConnectionSecurity::Native: The host certificate is validated using the native Operating System trust store.

§Documentation

https://signstar.archlinux.page/rustdoc/nethsm/ for development version of the crate
https://docs.rs/nethsm/latest/nethsm/ for released versions of the crate

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

§Testing

This library is integration tested against Nitrokey’s official nethsm container. To run these long running tests a podman installation is required. The tests handle the creation and teardown of containers as needed.

cargo test --all -- --ignored

§Re-exports

This crate relies on a set of external crates in its own public API.

Re-exports ensure that the respective dependencies do not have to be relied upon directly by consumers:

§Examples

Establish a connection with a Nitrokey NetHSM and manage credentials:

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

// Create a new connection to a NetHSM at "https://example.org" using admin credentials
let nethsm = NetHsm::new(
    Connection::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(
    Connection::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()?)?;

§Features

test-helpers enables the signstar_config::test module which provides utilities for test setups that are also useful for other crates.
_nethsm-integration-test enables tests that require podman for starting test dependencies in containers.

§Contributing

Please refer to the contributing guidelines to learn how to contribute to this project.

§License

This project may be used under the terms of the Apache-2.0 or MIT license.

Changes to this project - unless stated otherwise - automatically fall under the terms of both of the aforementioned licenses.

Modules§

container 🔒

Structs§

Container: A running container
NetHsmImage: An image of NetHSM used to create a running container.

Statics§

ADMIN_USER_ID: Identifier for an admin user.
ADMIN_USER_PASSPHRASE: Sample admin passphrase.
BACKUP_USER_ID: User ID for backup purposes.
BACKUP_USER_PASSPHRASE: Sample passphrase for the backup user.
BACKUP_USER_REAL_NAME: Real name for the backup user.
DEFAULT_AES_BITS: Default size for the AES key in bits.
DEFAULT_KEY_ID: Default ID for a key.
DEFAULT_OPERATOR_USER_ID: Default user ID for an operator.
DEFAULT_OPERATOR_USER_PASSPHRASE: Sample operator passphrase.
DEFAULT_OPERATOR_USER_REAL_NAME: Default real name for an operator.
DEFAULT_RSA_BITS: Default size of the RSA key in bits.
DEFAULT_TAG: Default tag.
ENC_KEY_ID: Default ID for the encryption key.
ENC_OPERATOR_USER_ID: User ID for the operator user who can access the encryption key.
ENC_OPERATOR_USER_PASSPHRASE: Sample passphrase for the operator user who can access the encryption key.
ENC_OPERATOR_USER_REAL_NAME: Real name for the operator user who can access the encryption key.
ENC_TAG: Default tag for the encryption key.
METRICS_USER_ID: User ID for the metrics user.
METRICS_USER_PASSPHRASE: Sample passphrase for the metrics user.
METRICS_USER_REAL_NAME: Real name for the metrics user.
NAMESPACE1: Sample namespace.
NAMESPACE2: Second namespace.
NAMESPACE1_ADMIN_REAL_NAME: Real name for namespace1’s administrator.
NAMESPACE1_ADMIN_USER_ID: Administrator’s user ID for namespace1.
NAMESPACE1_ADMIN_USER_PASSPHRASE: Sample passphrase for namespace1’s administrator.
NAMESPACE1_OPERATOR_REAL_NAME: Real name of an operator in namespace1.
NAMESPACE1_OPERATOR_USER_ID: User ID of an operator in namespace1.
NAMESPACE1_OPERATOR_USER_PASSPHRASE: Sample passphrase of an operator in namespace1.
NAMESPACE2_ADMIN_REAL_NAME: Real name for namespace2’s administrator.
NAMESPACE2_ADMIN_USER_ID: Administrator’s user ID for namespace2.
NAMESPACE2_ADMIN_USER_PASSPHRASE: Sample passphrase for namespace2’s administrator.
NAMESPACE2_OPERATOR_REAL_NAME: Real name of an operator in namespace2.
NAMESPACE2_OPERATOR_USER_ID: User ID of an operator in namespace2.
NAMESPACE2_OPERATOR_USER_PASSPHRASE: Sample passphrase of an operator in namespace2.
OTHER_KEY_ID: Default ID for a different key.
OTHER_OPERATOR_USER_ID: User ID for a different user.
OTHER_OPERATOR_USER_PASSPHRASE: Sample passphrase for a different user.
OTHER_OPERATOR_USER_REAL_NAME: Real name for a different user.
OTHER_TAG: Different tag.
UNLOCK_PASSPHRASE: Sample unlock passphrase.

Functions§

add_keys_to_nethsm 🔒
add_users_to_nethsm 🔒
create_container: Creates and starts a new NetHSM container.
create_nethsm: Creates a new NetHsm object configured with administrator credentials.
nethsm_with_keys: Adds users and keys to an already provisioned NetHSM container.
nethsm_with_users: Creates a new NetHsm object pointing at a NetHSM container with users.
provision_nethsm 🔒
provisioned_nethsm: Creates a new NetHsm object pointing at a provisioned NetHSM container.
unprovisioned_nethsm: Returns a new NetHsm object pointing to an unprovisioned NetHSM.
update_file: Downloads an update file if it’s not already present.

Module test

Module test Copy item path

§NetHSM

§Documentation

§Testing

§Re-exports

§Examples

§Features

§Contributing

§License

Modules§

Structs§

Statics§

Functions§

Module test