Struct DeviceConfig

Source

pub struct DeviceConfig {
    connection: RefCell<Connection>,
    credentials: RefCell<HashSet<ConfigCredentials>>,
    interactivity: ConfigInteractivity,
}

Expand description

The configuration for a [NetHsm]

Tracks the Connection for a [NetHsm] as well as a set of ConfigCredentials.

Fields§

§connection: RefCell<Connection>§credentials: RefCell<HashSet<ConfigCredentials>>§interactivity: ConfigInteractivity

Implementations§

Source §

impl DeviceConfig

Source

pub fn new( connection: Connection, credentials: Vec<ConfigCredentials>, interactivity: ConfigInteractivity, ) -> Result<DeviceConfig, Error>

Creates a new DeviceConfig

Creates a new DeviceConfig by providing a connection, an optional set of credentials and the interactivity setting.

§Errors

Returns an Error::CredentialsExist if credentials contains duplicates.

§Examples

use nethsm::{ConnectionSecurity, UserRole};
use nethsm_config::{ConfigCredentials, ConfigInteractivity, Connection, DeviceConfig};

let connection = Connection::new(
    "https://example.org/api/v1".parse()?,
    ConnectionSecurity::Unsafe,
);

DeviceConfig::new(
    connection.clone(),
    vec![],
    ConfigInteractivity::NonInteractive,
)?;

DeviceConfig::new(
    connection.clone(),
    vec![ConfigCredentials::new(
        UserRole::Operator,
        "user1".parse()?,
        Some("my-passphrase".to_string()),
    )],
    ConfigInteractivity::NonInteractive,
)?;

// this fails because the provided credentials contain duplicates
assert!(DeviceConfig::new(
    connection.clone(),
    vec![
        ConfigCredentials::new(
            UserRole::Operator,
            "user1".parse()?,
            Some("my-passphrase".to_string()),
        ),
        ConfigCredentials::new(
            UserRole::Operator,
            "user1".parse()?,
            Some("my-passphrase".to_string()),
        ),
    ],
    ConfigInteractivity::NonInteractive,
)
.is_err());

Source

pub fn set_config_interactivity(&mut self, config_type: ConfigInteractivity)

Sets the interactivity setting

NOTE: This method is not necessarily useful by itself, as one usually wants to use the same ConfigInteractivity as that of a Config, which holds the DeviceConfig.

Source

pub fn add_credentials( &self, credentials: ConfigCredentials, ) -> Result<(), Error>

Adds credentials to the device

Adds new ConfigCredentials to the DeviceConfig.

§Errors

Returns an Error::CredentialsExist if the credentials exist already.

§Examples

use nethsm::{ConnectionSecurity, UserRole};
use nethsm_config::{ConfigCredentials, ConfigInteractivity, Connection, DeviceConfig};

let connection = Connection::new(
    "https://example.org/api/v1".parse()?,
    ConnectionSecurity::Unsafe,
);

let device_config = DeviceConfig::new(
    connection.clone(),
    vec![],
    ConfigInteractivity::NonInteractive,
)?;

device_config.add_credentials(ConfigCredentials::new(
    UserRole::Operator,
    "user1".parse()?,
    Some("my-passphrase".to_string()),
))?;

// this fails because the credentials exist already
assert!(device_config
    .add_credentials(ConfigCredentials::new(
        UserRole::Operator,
        "user1".parse()?,
        Some("my-passphrase".to_string()),
    ))
    .is_err());

Source

pub fn get_credentials(&self, name: &UserId) -> Result<ConfigCredentials, Error>

Returns credentials by name

Returns existing ConfigCredentials from the DeviceConfig.

§Errors

Returns an Error::CredentialsMissing if no ConfigCredentials match the provided name.

§Examples

use nethsm::{ConnectionSecurity, UserRole};
use nethsm_config::{ConfigCredentials, ConfigInteractivity, Connection, DeviceConfig};
let connection = Connection::new(
    "https://example.org/api/v1".parse()?,
    ConnectionSecurity::Unsafe,
);

let device_config = DeviceConfig::new(
    connection.clone(),
    vec![],
    ConfigInteractivity::NonInteractive,
)?;

// this fails because the credentials do not exist
assert!(device_config.get_credentials(&"user1".parse()?).is_err());

device_config.add_credentials(ConfigCredentials::new(
    UserRole::Operator,
    "user1".parse()?,
    Some("my-passphrase".to_string()),
))?;

device_config.get_credentials(&"user1".parse()?)?;

Source

pub fn delete_credentials(&self, name: &UserId) -> Result<(), Error>

Deletes credentials by name

Deletes ConfigCredentials identified by name.

§Errors

Returns an Error::CredentialsMissing if no ConfigCredentials match the provided name.

§Examples

use nethsm::{ConnectionSecurity, UserRole};
use nethsm_config::{ConfigCredentials, ConfigInteractivity, Connection, DeviceConfig};

let device_config = DeviceConfig::new(
    Connection::new(
        "https://example.org/api/v1".parse()?,
        ConnectionSecurity::Unsafe,
    ),
    vec![],
    ConfigInteractivity::NonInteractive,
)?;
device_config.add_credentials(ConfigCredentials::new(
    UserRole::Operator,
    "user1".parse()?,
    Some("my-passphrase".to_string()),
))?;

device_config.delete_credentials(&"user1".parse()?)?;

// this fails because the credentials do not exist
assert!(device_config.delete_credentials(&"user1".parse()?).is_err());

Source

pub fn get_matching_credentials( &self, roles: &[UserRole], names: &[UserId], ) -> Result<ConfigCredentials, Error>

Returns credentials machting one or several roles and a optionally a name

Returns ConfigCredentials matching a list of [UserRole]s and/or a list of [UserId]s.

If names is empty, the ConfigCredentials first found matching one of the [UserRole]s provided using roles are returned. If names contains at least one entry, the first ConfigCredentials with a matching [UserId] that have at least one matching [UserRole] are returned.

§Errors

Returns an Error::NoMatchingCredentials if names is empty and no existing credentials match any of the provided roles. Returns an Error::CredentialsMissing if a [UserId] in names does not exist and no ConfigCredentials have been returned yet. Returns an Error::MatchingCredentialsMissing if no ConfigCredentials matching either the provided names or roles can be found.

§Examples

use nethsm::{ConnectionSecurity, UserRole};
use nethsm_config::{ConfigCredentials, ConfigInteractivity, Connection, DeviceConfig};

let device_config = DeviceConfig::new(
    Connection::new(
        "https://example.org/api/v1".parse()?,
        ConnectionSecurity::Unsafe,
    ),
    vec![ConfigCredentials::new(
        UserRole::Administrator,
        "admin1".parse()?,
        Some("my-passphrase".to_string()),
    )],
    ConfigInteractivity::NonInteractive,
)?;
device_config.add_credentials(ConfigCredentials::new(
    UserRole::Operator,
    "user1".parse()?,
    Some("my-passphrase".to_string()),
))?;

device_config.get_matching_credentials(&[UserRole::Operator], &["user1".parse()?])?;
device_config.get_matching_credentials(&[UserRole::Administrator], &["admin1".parse()?])?;
assert_eq!(
    device_config
        .get_matching_credentials(&[UserRole::Operator], &[])?
        .get_name(),
    "user1".parse()?
);
assert_eq!(
    device_config
        .get_matching_credentials(&[UserRole::Administrator], &[])?
        .get_name(),
    "admin1".parse()?
);

// this fails because we must provide a role to match against
assert!(device_config
    .get_matching_credentials(&[], &["user1".parse()?])
    .is_err());

// this fails because no user in the requested role exists
assert!(device_config
    .get_matching_credentials(&[UserRole::Metrics], &[])
    .is_err());

// this fails because no user with the name first provided exists
assert!(device_config
    .get_matching_credentials(&[UserRole::Operator], &["user2".parse()?, "user1".parse()?])
    .is_err());

// this fails because no user in the requested role with any of the provided names exists
assert!(device_config
    .get_matching_credentials(&[UserRole::Metrics], &["admin1".parse()?, "user1".parse()?])
    .is_err());

Source

pub fn nethsm_with_matching_creds( &self, roles: &[UserRole], names: &[UserId], passphrases: &[Passphrase], ) -> Result<NetHsm, Error>

Returns a [NetHsm] based on the DeviceConfig (optionally with one set of credentials)

Creates a [NetHsm] based on the DeviceConfig. Only if roles is not empty, one set of ConfigCredentials based on roles, names and passphrases is added to the [NetHsm].

WARNING: Depending on the ConfigInteractivity chosen when initializing the DeviceConfig this method behaves differently with regards to adding credentials!

§`NonInteractive`

If roles is not empty, optionally adds one set of ConfigCredentials found by get_matching_credentials to the returned [NetHsm], based on roles and names. If the found ConfigCredentials do not contain a passphrase, a [Passphrase] in pasphrases with the same index as that of the [UserId] in names is used.

§`Interactive`

If roles is not empty, optionally attempts to add one set of ConfigCredentials with the help of get_matching_credentials to the returned [NetHsm], based on roles and names. If no ConfigCredentials are found by get_matching_credentials, users are interactively prompted for providing a user name. If the found or prompted for [UserId] ConfigCredentials do not contain a passphrase, a [Passphrase] in pasphrases with the same index as that of the [UserId] in names is used. If get_matching_credentials, or those the user has been prompted for provides ConfigCredentials without a passphrase, a [Passphrase] in pasphrases with the same index as that of the [UserId] in names is used. If none is provided (at the right location) in passphrases, the user is prompted for a passphrase interactively.

§Errors

Returns an Error::NoMatchingCredentials, Error::CredentialsMissing, or Error::MatchingCredentialsMissing if the DeviceConfig is initialized with Interactive and get_matching_credentials is unable to return ConfigCredentials based on roles and names.

Returns an Error::NonInteractive if the DeviceConfig is initialized with NonInteractive, but additional data would be requested interactively.

Returns an Error::Prompt if requesting additional data interactively leads to error.

§Examples

use nethsm::{ConnectionSecurity, Passphrase, UserRole};
use nethsm_config::{ConfigCredentials, ConfigInteractivity, Connection, DeviceConfig};

let device_config = DeviceConfig::new(
    Connection::new(
        "https://example.org/api/v1".parse()?,
        ConnectionSecurity::Unsafe,
    ),
    vec![ConfigCredentials::new(
        UserRole::Administrator,
        "admin1".parse()?,
        Some("my-passphrase".to_string()),
    )],
    ConfigInteractivity::NonInteractive,
)?;
device_config.add_credentials(ConfigCredentials::new(
    UserRole::Operator,
    "user1".parse()?,
    None,
))?;

// NetHsm with Operator credentials
// this works non-interactively, although the credentials in the config provide no passphrase, because we provide the passphrase manually
device_config.nethsm_with_matching_creds(
    &[UserRole::Operator],
    &["user1".parse()?],
    &[Passphrase::new("my-passphrase".to_string())],
)?;

// NetHsm with Administrator credentials
// this automatically selects "admin1" as it is the only user in the Administrator role
// this works non-interactively, because the credentials in the config provide a passphrase!
device_config.nethsm_with_matching_creds(
    &[UserRole::Administrator],
    &[],
    &[],
)?;

// a NetHsm without any credentials
device_config.nethsm_with_matching_creds(
    &[],
    &[],
    &[],
)?;

// this fails because the config is non-interactive, the targeted credentials do not offer a passphrase and we also provide none
assert!(device_config.nethsm_with_matching_creds(
    &[UserRole::Operator],
    &["user1".parse()?],
    &[],
).is_err());

// this fails because the config is non-interactive and the targeted credentials do not exist
assert!(device_config.nethsm_with_matching_creds(
    &[UserRole::Operator],
    &["user2".parse()?],
    &[],
).is_err());

// this fails because the config is non-interactive and no user in the targeted role exists
assert!(device_config.nethsm_with_matching_creds(
    &[UserRole::Metrics],
    &[],
    &[],
).is_err());