Struct DeviceConfig

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

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

impl DeviceConfig

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::{Connection, ConnectionSecurity, UserRole};
use nethsm_config::{ConfigCredentials, ConfigInteractivity, 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()
);

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.

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::{Connection, ConnectionSecurity, UserRole};
use nethsm_config::{ConfigCredentials, ConfigInteractivity, 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()
);

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::{Connection, ConnectionSecurity, UserRole};
use nethsm_config::{ConfigCredentials, ConfigInteractivity, 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()?)?;

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::{Connection, ConnectionSecurity, UserRole};
use nethsm_config::{ConfigCredentials, ConfigInteractivity, 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());

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::{Connection, ConnectionSecurity, UserRole};
use nethsm_config::{ConfigCredentials, ConfigInteractivity, 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()
);

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::{Connection, ConnectionSecurity, Passphrase, UserRole};
use nethsm_config::{ConfigCredentials, ConfigInteractivity, 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());

Trait Implementations

impl Clone for DeviceConfig

fn clone(&self) -> DeviceConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DeviceConfig

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for DeviceConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for DeviceConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<&DeviceConfig> for NetHsm

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &DeviceConfig) -> Result<Self, Error>

Performs the conversion.

impl TryFrom<DeviceConfig> for NetHsm

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: DeviceConfig) -> Result<Self, Error>

Performs the conversion.