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:
nethsm_sdk_rs::models::DistinguishedName
nethsm_sdk_rs::models::NetworkConfig
nethsm_sdk_rs::models::SystemState
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:
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.
§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§
- Certificate fingerprints to use for matching against a host’s TLS certificate
- A network connection to a NetHSM
- The key data required when importing a secret key
- The URL used for connecting to a NetHSM instance
Enums§
- The NetHSM boot mode
- The security model chosen for a
crate::NetHsm
’s TLS connection - A mode for decrypting a message
- A mode for encrypting a message
- A mechanism which can be used with a key
- The algorithm type of a key
- A device log level
- The type of a signature
- The algorithm type of a key used for TLS
- The role of a user on a NetHSM device