Crate nethsm

Source
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:

§Documentation

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.

Re-exports§

pub use connection::Connection;
pub use connection::Url;
pub use openpgp::extract_certificate as extract_openpgp_certificate;
pub use openpgp::tsk_to_private_key_import;

Modules§

backup 🔒
Backup handling.
base 🔒
Functionality for accessing a NetHsm.
connection
Components for NetHSM connection handling.
error 🔒
Error handling for NetHsm.
key 🔒
nethsm_sdk 🔒
openpgp
OpenPGP-related functions.
tls 🔒
user 🔒
Module for credentials, user IDs and passphrases.

Structs§

Credentials
Credentials for a NetHsm
DateTime
ISO 8601 combined date and time with time zone.
DistinguishedName
FullCredentials
Credentials for a NetHsm.
HostCertificateFingerprints
Certificate fingerprints to use for matching against a host’s TLS certificate
InfoData
KeyId
A unique key identifier for a private key on a NetHSM.
LoggingConfig
NamespaceId
The ID of a NetHsm namespace
NetHsm
A network connection to a NetHSM.
NetworkConfig
OpenPgpKeyUsageFlags
Key usage flags that can be set on the generated certificate.
OpenPgpUserId
A basic representation of a User ID for OpenPGP
OpenPgpUserIdList
A list of OpenPgpUserId
Passphrase
A secret passphrase
PrivateKeyImport
The key data required when importing a secret key
PublicKey
SigningKeySetup
The validated setup for a cryptographic signing key
SystemInfo
SystemUpdateData
UserData
Utc
The UTC time zone. This is the most efficient time zone when you don’t need the local time. It is also used as an offset (which is also a dummy type).

Enums§

BootMode
The NetHSM boot mode
ConnectionSecurity
The security model chosen for a crate::NetHsm’s TLS connection
CryptographicKeyContext
The cryptographic context in which a key is used.
DecryptMode
A mode for decrypting a message
EncryptMode
A mode for encrypting a message
Error
An error that may occur when using a NetHSM.
KeyFormat
The format of a key
KeyMechanism
A mechanism which can be used with a key
KeyType
The algorithm type of a key
LogLevel
A device log level
OpenPgpVersion
The OpenPGP version
SignatureType
The type of a signature.
SystemState
TlsKeyType
The algorithm type of a key used for TLS
UserError
An error that may occur when operating on users.
UserId
The ID for a NetHsm user
UserRole
The role of a user on a NetHSM device

Constants§

DEFAULT_MAX_IDLE_CONNECTIONS
The default maximum idle TLS connections for a NetHsm.
DEFAULT_TIMEOUT_SECONDS
The default timeout in seconds for a TLS connections for a NetHsm.

Functions§

key_type_and_mechanisms_match_signature_type
Ensures that a KeyType and a list of KeyMechanisms is compatible with a SignatureType
key_type_matches_length
Ensures that a KeyType is compatible with an optional key length
key_type_matches_mechanisms
Ensures that a KeyType is compatible with a list of KeyMechanisms
tls_key_type_matches_length
Ensures that a TlsKeyType is compatible with an optional key length
validate_backup
Validates a backup.