Struct NetHsmBackend

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

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 AdminCredentials and HermeticParallelConfig.

Fields

nethsm: NetHsm

admin_credentials: &'a AdminCredentials

signstar_config: &'b HermeticParallelConfig

Implementations

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

pub fn new( nethsm: NetHsm, admin_credentials: &'a AdminCredentials, signstar_config: &'b HermeticParallelConfig, ) -> 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::{FullCredentials, Connection, ConnectionSecurity, NetHsm};
use nethsm_config::{
    AdministrativeSecretHandling,
    AuthorizedKeyEntryList,
    ConfigInteractivity,
    ConfigSettings,
    HermeticParallelConfig,
    NonAdministrativeSecretHandling,
    UserMapping,
};
use signstar_config::{AdminCredentials, NetHsmBackend};

// 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 = AdminCredentials::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 = HermeticParallelConfig::new(
    ConfigSettings::new(
        "my_app".to_string(),
        ConfigInteractivity::NonInteractive,
        None,
    ),
    1,
    AdministrativeSecretHandling::ShamirsSecretSharing,
    NonAdministrativeSecretHandling::SystemdCreds,
    HashSet::from([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_keys: AuthorizedKeyEntryList::new(vec!["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOh96uFTnvX6P1ebbLxXFvy6sK7qFqlMHDOuJ0TmuXQQ user@host".parse()?])?,
        },
        UserMapping::SystemOnlyShareUpload {
            system_user: "ssh-share-up".parse()?,
            ssh_authorized_keys: AuthorizedKeyEntryList::new(vec!["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOh96uFTnvX6P1ebbLxXFvy6sK7qFqlMHDOuJ0TmuXQQ user@host".parse()?])?,
        }]),
)?;

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

pub fn state(&self) -> Result<State, Error>

Creates a new State for the [NetHsm] backend.

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

• retrieving the system state of the tracked [NetHsm] fails,
• unlocking a locked [NetHsm] backend fails,
• or retrieving the state of users or keys on the tracked [NetHsm] 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.