Struct NetHsmBackend 

pub struct NetHsmBackend<'a, 'b> {
    nethsm: NetHsm,
    admin_credentials: &'a NetHsmAdminCredentials,
    signstar_config: &'b SignstarConfig,
}

A NetHSM backend that provides full control over its data.

This backend allows full control over the data in a [NetHsm], to the extend that is configured by the tracked NetHsmAdminCredentials and SignstarConfig.

Fields

nethsm: NetHsm

admin_credentials: &'a NetHsmAdminCredentials

signstar_config: &'b SignstarConfig

Implementations

impl<'a, 'b> NetHsmBackend<'a, 'b>

pub fn new( nethsm: NetHsm, admin_credentials: &'a NetHsmAdminCredentials, signstar_config: &'b SignstarConfig, ) -> Result<Self, Error>

Creates a new NetHsmBackend.

Errors

Returns an error if

• the iteration of the admin_credentials does not match that of the signstar_config,
• or retrieving the default administrator from the admin_credentials fails.

Examples

use std::collections::HashSet;

use nethsm::{Connection, ConnectionSecurity, FullCredentials, NetHsm};
use signstar_config::{
    NetHsmAdminCredentials,
    AdministrativeSecretHandling,
    BackendConnection,
    NetHsmBackend,
    NonAdministrativeSecretHandling,
    SignstarConfig,
    UserMapping,
};

// The NetHSM connection.
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    None,
    None,
    None,
)?;
// The administrative credentials.
let admin_credentials = NetHsmAdminCredentials::new(
    1,
    "backup-passphrase".parse()?,
    "unlock-passphrase".parse()?,
    vec![FullCredentials::new(
        "admin".parse()?,
        "admin-passphrase".parse()?,
    )],
    vec![FullCredentials::new(
        "ns1~admin".parse()?,
        "ns1-admin-passphrase".parse()?,
    )],
)?;
// The Signstar config.
let signstar_config = SignstarConfig::new(
    1,
    AdministrativeSecretHandling::ShamirsSecretSharing,
    NonAdministrativeSecretHandling::SystemdCreds,
    HashSet::from([BackendConnection::NetHsm(Connection::new(
        "https://localhost:8443/api/v1/".parse()?,
        "Unsafe".parse()?,
    ))]),
    HashSet::from([
        UserMapping::NetHsmOnlyAdmin("admin".parse()?),
        UserMapping::SystemOnlyShareDownload {
            system_user: "ssh-share-down".parse()?,
            ssh_authorized_key: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOh96uFTnvX6P1ebbLxXFvy6sK7qFqlMHDOuJ0TmuXQQ user@host".parse()?,
        },
        UserMapping::SystemOnlyShareUpload {
            system_user: "ssh-share-up".parse()?,
            ssh_authorized_key: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOh96uFTnvX6P1ebbLxXFvy6sK7qFqlMHDOuJ0TmuXQQ user@host".parse()?,
        }]),
)?;

let nethsm_backend = NetHsmBackend::new(nethsm, &admin_credentials, &signstar_config)?;

pub fn nethsm(&self) -> &NetHsm

Returns a reference to the tracked [NetHsm].

pub(crate) fn unlock_nethsm(&self) -> Result<(), Error>

Unlocks a locked [NetHsm] backend.

pub(crate) fn user_states(&self) -> Result<Vec<UserState>, Error>

Retrieves the state for all users on the [NetHsm] backend.

Note

Uses the nethsm with the default R-Administrator.

Errors

Returns an error if

• using the credentials of the default R-Administrator fails,
• retrieving all user names of the NetHSM backend fails,
• retrieving information about a specific NetHSM user fails,
• or retrieving the tags of an Operator user fails.

fn key_certificate_state( &self, key_id: &KeyId, namespace: Option<&NamespaceId>, ) -> KeyCertificateState

Retrieves the state of a key certificate on the [NetHsm] backend.

Key certificates may be retrieved for system-wide keys or namespaced keys. Returns a KeyCertificateState, which may also encode reasons for why state cannot be retrieved.

Note

It is assumed that the current credentials for the nethsm provide access to the key certificate of key key_id.

pub(crate) fn key_states(&self) -> Result<Vec<KeyState>, Error>

Retrieves the state for all keys on the [NetHsm] backend.

Collects each key, their KeyType and list of KeyMechanisms. Also attempts to derive a CryptographicKeyContext from the key certificate.

Note

This function uses the nethsm with the default R-Administrator, but may switch to a namespace-specific N-Administrator for individual operations. If this function succeeds, the nethsm is guaranteed to use the default R-Administrator again. If this function fails, the nethsm may still use a namespace-specific N-Administrator.

Errors

Returns an error if

• using the default R-Administrator for authentication against the backend fails,
• retrieving the names of all system-wide keys on the backend fails,
• retrieving information on a specific system-wide key on the backend fails,
• an N-Administrator in admin_credentials is not actually in a namespace,
• using the credentials of an N-Administrator fails,
• retrieving the names of all namespaced keys on the backend fails,
• or retrieving information on a specific namespaced key on the backend fails.

pub fn sync(&self, user_credentials: &[FullCredentials]) -> Result<(), Error>

Syncs the state of a Signstar configuration with the backend using credentials for users in non-administrative roles.

Provisions unprovisioned NetHSM backends and unlocks locked ones. Then works down the following list to

• create R-Administrators,
  • or set their passphrase if they exist already,
• create system-wide keys and add tags to them,
  • or remove all tags from existing keys and only add the configured tags,
• create users in the system-wide, non-administrative roles (i.e. [Backup][UserRole::Backup], [Metrics][UserRole::Metrics] and [Operator][UserRole::Operator]),
  • or set their passphrase if they exist already,
• create OpenPGP certificates for system-wide keys,
  • or do nothing if they exist already,
• create N-Administrators and their respective namespaces,
  • or set their passphrase if they exist already,
• create namespaced keys and add tags to them,
  • or remove all tags from existing keys and only add the configured tags,
• create users in the namespaced, non-administrative roles (i.e. [Operator][UserRole::Operator]),
  • or set their passphrase if they exist already,
• and create OpenPGP certificates for namespaced keys,
  • or do nothing if they exist already.

Note

This function uses the nethsm with the default R-Administrator, but may switch to a namespace-specific N-Administrator or non-administrative user for individual operations. If this function succeeds, the nethsm is guaranteed to use the default R-Administrator again. If this function fails, the nethsm may still use a namespace-specific N-Administrator or non-administrative user.

Errors

Returns an error if

• retrieving the state of the [NetHsm] backend fails,
• provisioning an unprovisioned [NetHsm] fails,
• unlocking a locked [NetHsm] backend fails,
• adding users in the system-wide [Administrator][UserRole::Administrator] role fails,
• adding system-wide keys fails,
• adding system-wide users in the [Backup][UserRole::Backup], [Metrics][UserRole::Metrics] or [Operator][UserRole::Operator] role fails,
• adding OpenPGP certificates for system-wide keys fails,
• adding namespaced users in the [Administrator][UserRole::Administrator] role or adding their respective namespace fails,
• adding namespaced keys fails,
• adding namespaced users in the [Operator][UserRole::Operator] role fails,
• or adding OpenPGP certificates for namespaced keys fails.

Trait Implementations

impl<'a, 'b> Debug for NetHsmBackend<'a, 'b>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, 'b> TryFrom<&NetHsmBackend<'a, 'b>> for NetHsmState

fn try_from(value: &NetHsmBackend<'_, '_>) -> Result<Self, Self::Error>

Creates a new NetHsmState from a NetHsmBackend.

Note

Uses the [NetHsm] backend with the default R-Administrator, but may switch to a namespace-specific N-Administrator for individual operations. If this function succeeds, the nethsm is guaranteed to use the default R-Administrator again. If this function fails, the nethsm may still use a namespace-specific N-Administrator.

Errors

Returns an error if

• retrieving the system state of the [NetHsm] backend fails,
• unlocking a locked [NetHsm] backend fails,
• or retrieving the state of users or keys on the tracked [NetHsm] backend fails.

type Error = Error

The type returned in the event of a conversion error.