Crate nethsm

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:

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.

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::{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()?)?;

Re-exports§

pub use connection::Connection;
pub use connection::Url;

Modules§

connection: Components for NetHSM connection handling.
key 🔒
nethsm_sdk 🔒
openpgp 🔒: OpenPGP-related functions.
tls 🔒
user 🔒: Module for credentials, user IDs and passphrases.

Structs§

Credentials: Credentials for a NetHsm
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

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§

MIN_RSA_BIT_LENGTH: The minimum bit length for an RSA key

Functions§

extract_openpgp_certificate: Extracts certificate (public key) from an OpenPGP TSK.
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
tsk_to_private_key_import: Converts an OpenPGP Transferable Secret Key into PrivateKeyImport object.
validate_backup: Validates a backup.

Crate nethsmCopy item path