Struct NetHsm 

pub struct NetHsm {
    agent: RefCell<Agent>,
    url: RefCell<Url>,
    current_credentials: RefCell<Option<UserId>>,
    credentials: RefCell<HashMap<UserId, Credentials>>,
}

A network connection to a NetHSM.

Defines a network configuration for the connection and a list of user [Credentials] that can be used over this connection.

Fields

agent: RefCell<Agent>

url: RefCell<Url>

current_credentials: RefCell<Option<UserId>>

credentials: RefCell<HashMap<UserId, Credentials>>

Implementations

impl NetHsm

pub fn new( connection: Connection, credentials: Option<Credentials>, max_idle_connections: Option<usize>, timeout_seconds: Option<u64>, ) -> Result<NetHsm, Error>

Creates a new NetHSM connection.

Creates a new NetHSM connection based on a Connection.

Optionally initial credentials (used when communicating with the NetHSM), max_idle_connections to set the size of the connection pool (defaults to 100) and timeout_seconds to set the timeout for a successful socket connection (defaults to 10) can be provided.

Errors

• the TLS client configuration can not be created,
• or [ConnectionSecurity::Native] is provided as tls_security, but no certification authority certificates are available on the system.

pub fn set_agent( &self, tls_security: ConnectionSecurity, max_idle_connections: Option<usize>, timeout_seconds: Option<u64>, ) -> Result<(), Error>

Sets the connection agent for the NetHSM connection.

Allows setting the

• [ConnectionSecurity] which defines the TLS security model for the connection,
• maximum idle connections per host using the optional max_idle_connections (defaults to [available_parallelism] and falls back to 100 if unavailable),
• and timeout in seconds for a successful socket connection using the optional timeout_seconds (defaults to 10).

Errors

Returns an error if

• the TLS client configuration can not be created,
• [ConnectionSecurity::Native] is provided as tls_security, but no certification authority certificates are available on the system.

Examples

use nethsm::{Connection, ConnectionSecurity, NetHsm, Url};

// Create a new connection for a NetHSM at "https://example.org"
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    None,
    None,
    None,
)?;

// change the connection agent to something else
nethsm.set_agent(ConnectionSecurity::Unsafe, Some(200), Some(30))?;

pub fn set_url(&self, url: Url)

Sets the URL for the NetHSM connection.

Examples

use nethsm::{Connection, ConnectionSecurity, NetHsm, Url};

// Create a new connection for a NetHSM at "https://example.org"
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    None,
    None,
    None,
)?;

// change the url to something else
nethsm.set_url(Url::new("https://other.org/api/v1")?);

pub fn get_url(&self) -> Url

Retrieves the current URL for the NetHSM connection.

Examples

use nethsm::{Connection, ConnectionSecurity, NetHsm, Url};

// Create a new connection for a NetHSM at "https://example.org"
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    None,
    None,
    None,
)?;

// retrieve the current URL
assert_eq!(nethsm.get_url(), "https://example.org/api/v1".try_into()?);

pub fn add_credentials(&self, credentials: Credentials)

Adds [Credentials] to the list of available ones.

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase};

let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    None,
    None,
    None,
)?;

// add credentials
nethsm.add_credentials(Credentials::new(
    "admin".parse()?,
    Some(Passphrase::new("passphrase".to_string())),
));
nethsm.add_credentials(Credentials::new(
    "user1".parse()?,
    Some(Passphrase::new("other_passphrase".to_string())),
));
nethsm.add_credentials(Credentials::new("user2".parse()?, None));

pub fn remove_credentials(&self, user_id: &UserId)

Removes [Credentials] from the list of available and currently used ones.

Removes [Credentials] from the list of available ones and if identical unsets the ones used for further authentication as well.

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase};

let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// remove credentials
nethsm.remove_credentials(&"admin".parse()?);

pub fn use_credentials(&self, user_id: &UserId) -> Result<(), Error>

Sets [Credentials] to use for the next connection.

Errors

An Error is returned if no [Credentials] with the UserId user_id can be found.

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase};

let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    None,
    None,
    None,
)?;

// add credentials
nethsm.add_credentials(Credentials::new(
    "admin".parse()?,
    Some(Passphrase::new("passphrase".to_string())),
));
nethsm.add_credentials(Credentials::new(
    "user1".parse()?,
    Some(Passphrase::new("other_passphrase".to_string())),
));

// use admin credentials
nethsm.use_credentials(&"admin".parse()?)?;

// use operator credentials
nethsm.use_credentials(&"user1".parse()?)?;

// this fails, because the user has not been added yet
assert!(nethsm.use_credentials(&"user2".parse()?).is_err());

pub fn get_current_user(&self) -> Option<UserId>

Get the UserId of the currently used [Credentials] for the connection.

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm};

let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some("passphrase".parse()?),
    )),
    None,
    None,
)?;

// Get current User ID
assert_eq!(nethsm.get_current_user(), Some("admin".parse()?));

impl NetHsm

pub fn generate_key( &self, key_type: KeyType, mechanisms: Vec<KeyMechanism>, length: Option<u32>, key_id: Option<KeyId>, tags: Option<Vec<String>>, ) -> Result<KeyId, Error>

Generates a new key on the NetHSM.

Generates a new key with customizable features on the NetHSM. The provided KeyType and list of KeyMechanisms have to match:

• KeyType::Rsa requires one of KeyMechanism::RsaDecryptionRaw, KeyMechanism::RsaDecryptionPkcs1, KeyMechanism::RsaDecryptionOaepMd5, KeyMechanism::RsaDecryptionOaepSha1, KeyMechanism::RsaDecryptionOaepSha224, KeyMechanism::RsaDecryptionOaepSha256, KeyMechanism::RsaDecryptionOaepSha384, KeyMechanism::RsaDecryptionOaepSha512, KeyMechanism::RsaSignaturePkcs1, KeyMechanism::RsaSignaturePssSha1, KeyMechanism::RsaSignaturePssSha224, KeyMechanism::RsaSignaturePssSha256, KeyMechanism::RsaSignaturePssSha384 or KeyMechanism::RsaSignaturePssSha512
• KeyType::Curve25519 requires KeyMechanism::EdDsaSignature
• KeyType::EcP256, KeyType::EcP384 and KeyType::EcP521 require KeyMechanism::EcdsaSignature
• KeyType::Generic requires one of KeyMechanism::AesDecryptionCbc or KeyMechanism::AesEncryptionCbc

Optionally the key bit-length using length, a custom key ID using key_id and a list of tags to be attached to the new key can be provided. If no key_id is provided, a unique one is generated automatically.

WARNING: If no tags are provided, the generated key is usable by all users in the [Operator][UserRole::Operator] role in the same scope (e.g. same namespace) by default!

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• Keys generated by N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) are only visible to users in their namespace. Only users in the [Operator][UserRole::Operator] role in that same namespace can be granted access to them.
• Keys generated by R-Administrators (system-wide [Administrator][UserRole::Administrator] users) are only visible to system-wide users. Only system-wide users in the [Operator][UserRole::Operator] role (not in any namespace) can be granted access to them.

Errors

Returns an Error::Api if generating the key fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• a key identified by key_id exists already
• the chosen length or tags options are not valid
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role

Returns an Error::Key if

• the provided combination of key_type and mechanisms is not valid.
• the provided combination of key_type and length is not valid.

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    Passphrase,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// generate a Curve25519 key for signing with custom Key ID and tags
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["sign_tag1".to_string(), "sign_tag2".to_string()]),
)?;

// generate a generic key for symmetric encryption and decryption
nethsm.generate_key(
    KeyType::Generic,
    vec![
        KeyMechanism::AesEncryptionCbc,
        KeyMechanism::AesDecryptionCbc,
    ],
    Some(128),
    Some("encryption1".parse()?),
    Some(vec!["encryption_tag1".to_string()]),
)?;

pub fn import_key( &self, mechanisms: Vec<KeyMechanism>, key_data: PrivateKeyImport, key_id: Option<KeyId>, tags: Option<Vec<String>>, ) -> Result<KeyId, Error>

Imports an existing private key.

Imports an existing key with custom features into the NetHSM. The KeyType implied by the provided PrivateKeyImport and the list of KeyMechanisms have to match:

• KeyType::Rsa must be used with KeyMechanism::RsaDecryptionRaw, KeyMechanism::RsaDecryptionPkcs1, KeyMechanism::RsaDecryptionOaepMd5, KeyMechanism::RsaDecryptionOaepSha1, KeyMechanism::RsaDecryptionOaepSha224, KeyMechanism::RsaDecryptionOaepSha256, KeyMechanism::RsaDecryptionOaepSha384, KeyMechanism::RsaDecryptionOaepSha512, KeyMechanism::RsaSignaturePkcs1, KeyMechanism::RsaSignaturePssSha1, KeyMechanism::RsaSignaturePssSha224, KeyMechanism::RsaSignaturePssSha256, KeyMechanism::RsaSignaturePssSha384 or KeyMechanism::RsaSignaturePssSha512
• KeyType::Curve25519 must be used with KeyMechanism::EdDsaSignature
• KeyType::EcP256, KeyType::EcP384 and KeyType::EcP521 must be used with KeyMechanism::EcdsaSignature
• KeyType::Generic must be used with KeyMechanism::AesDecryptionCbc or KeyMechanism::AesEncryptionCbc

Optionally a custom Key ID using key_id and a list of tags to be attached to the new key can be provided. If no key_id is provided, a unique one is generated automatically.

WARNING: If no tags are provided, the imported key is usable by all users in the [Operator][UserRole::Operator] role in the same scope (e.g. same namespace) by default!

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• Keys imported by N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) are only visible to users in their namespace. Only users in the [Operator][UserRole::Operator] role in that same namespace can be granted access to them.
• Keys imported by R-Administrators (system-wide [Administrator][UserRole::Administrator] users) are only visible to system-wide users. Only system-wide users in the [Operator][UserRole::Operator] role (not in any namespace) can be granted access to them.

Errors

Returns an Error::Api if importing the key fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• a key identified by key_id exists already
• the chosen tags option is not valid
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role

Returns an Error::Key if the provided combination of key_data and mechanisms is not valid.

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, PrivateKeyImport, KeyMechanism, KeyType, NetHsm, Passphrase};
use rsa::pkcs8::{DecodePrivateKey, EncodePrivateKey};
use rsa::RsaPrivateKey;

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// create a 4096 bit RSA private key and return it as PKCS#8 private key in ASN.1 DER-encoded format
let private_key = {
    let mut rng = rand::thread_rng();
    let private_key = RsaPrivateKey::new(&mut rng, 4096)?;
    private_key.to_pkcs8_der()?
};

// import an RSA key for PKCS1 signatures
nethsm.import_key(
    vec![KeyMechanism::RsaSignaturePkcs1],
    PrivateKeyImport::new(KeyType::Rsa, private_key.as_bytes())?,
    Some("signing2".parse()?),
    Some(vec!["signing_tag3".to_string()]),
)?;

pub fn delete_key(&self, key_id: &KeyId) -> Result<(), Error>

Deletes a key from the NetHSM.

Deletes a key identified by key_id from the NetHSM.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• Keys in a namespace can only be deleted by N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) of that namespace (R-Administrators have no access to keys in a namespace). NOTE: Calling delete_namespace deletes all keys in a namespace!
• System-wide keys can only be deleted by R-Administrators (system-wide [Administrator][UserRole::Administrator] users).

Errors

Returns an Error::Api if deleting the key fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// delete a key with the Key ID "signing1"
nethsm.delete_key(&"signing1".parse()?)?;

pub fn get_key(&self, key_id: &KeyId) -> Result<PublicKey, Error>

Gets details about a key.

Gets details about a key identified by key_id.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] or [Operator][UserRole::Operator] role.

Namespaces

• Users in a namespace can only get details about keys in their own namespace.
• System-wide users (not in a namespace) can only get details about system-wide keys.

Errors

Returns an Error::Api if getting the key details fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists
• the used [Credentials] are not correct
• the used [Credentials] are not those of a user in the [Administrator][UserRole::Administrator] or [Operator][UserRole::Operator] role

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// get details on a key with the Key ID "signing1"
println!("{:?}", nethsm.get_key(&"signing1".parse()?)?);

pub fn get_keys(&self, filter: Option<&str>) -> Result<Vec<KeyId>, Error>

Gets a list of Key IDs on the NetHSM.

Optionally filter can be provided for matching against Key IDs.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] or [Operator][UserRole::Operator] role.

Namespaces

• Users in a namespace can only list key IDs of keys in their own namespace.
• System-wide users (not in a namespace) can only list key IDs of system-wide keys.

Errors

Returns an Error::Api if getting the list of Key IDs fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not those of a user in the [Administrator][UserRole::Administrator] or [Operator][UserRole::Operator] role

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// get all Key IDs
println!("{:?}", nethsm.get_keys(None)?);

// get all Key IDs that begin with "signing"
println!("{:?}", nethsm.get_keys(Some("signing"))?);

pub fn get_public_key(&self, key_id: &KeyId) -> Result<String, Error>

Gets the public key of a key on the NetHSM.

Gets the public key of a key on the NetHSM, identified by key_id. The public key is returned in X.509 Privacy-Enhanced Mail (PEM) format.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] or [Operator][UserRole::Operator] role.

Namespaces

• Users in a namespace can only get public keys of keys in their own namespace.
• System-wide users (not in a namespace) can only get public keys of system-wide keys.

Errors

Returns an Error::Api if getting the public key fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] or [Operator][UserRole::Operator] role
• the targeted key is a symmetric key (i.e. KeyType::Generic) and therefore can not provide a public key

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    Passphrase,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;

// get public key for a key with Key ID "signing1"
println!("{:?}", nethsm.get_public_key(&"signing1".parse()?)?);

pub fn add_key_tag(&self, key_id: &KeyId, tag: &str) -> Result<(), Error>

Adds a tag for a key.

Adds tag for a key, identified by key_id.

A tag for a key is prerequisite to adding the same tag to a user in the [Operator][UserRole::Operator] role and thus granting it access to the key.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) are only able to tag keys in their own namespace.
• R-Administrators (system-wide [Administrator][UserRole::Administrator] users) are only able to tag system-wide keys.

Errors

Returns an Error::Api if adding a tag to a key fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists
• tag is already associated with the key
• tag is invalid
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role
• a key in a namespace is attempted to be tagged by an R-Administrator
• a system-wide key is attempted to be tagged by an N-Administrator

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    Passphrase,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;

// add the tag "important" to a key with Key ID "signing1"
nethsm.add_key_tag(&"signing1".parse()?, "important")?;

pub fn delete_key_tag(&self, key_id: &KeyId, tag: &str) -> Result<(), Error>

Deletes a tag from a key.

Deletes tag from a key, identified by key_id on the NetHSM.

Deleting a tag from a key removes access to it for any user in the [Operator][UserRole::Operator] role, that carries the same tag.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) are only able to delete tags from keys in their own namespace.
• R-Administrators (system-wide [Administrator][UserRole::Administrator] users) are only able to delete tags from system-wide keys.

Errors

Returns an Error::Api if adding a tag to a key fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists
• tag is not associated with the key
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role
• the tag for a key in a namespace is attempted to be removed by an R-Administrator
• the tag for a system-wide key is attempted to be removed by an N-Administrator

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    Passphrase,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string(), "important".to_string()]),
)?;

// remove the tag "important" from a key with Key ID "signing1"
nethsm.delete_key_tag(&"signing1".parse()?, "important")?;

pub fn import_key_certificate( &self, key_id: &KeyId, data: Vec<u8>, ) -> Result<(), Error>

Imports a certificate for a key.

Imports a certificate for a key identified by key_id. Certificates up to 1 MiB in size are supported. NOTE: The imported bytes are not validated!

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) are only able to import certificates for keys in their own namespace.
• R-Administrators (system-wide [Administrator][UserRole::Administrator] users) are only able to import certificates for system-wide keys.

Errors

Returns an Error::Api if importing a certificate for a key fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists
• the data is invalid
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    OpenPgpKeyUsageFlags,
    OpenPgpVersion,
    Passphrase,
    Timestamp,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator1".to_string(),
    UserRole::Operator,
    Passphrase::new("operator-passphrase".to_string()),
    Some("operator1".parse()?),
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;
// tag system-wide user in Operator role for access to signing key
nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;
// use the Operator credentials to create an OpenPGP certificate for a key
nethsm.use_credentials(&"operator1".parse()?)?;
let openpgp_cert = nethsm.create_openpgp_cert(
    &"signing1".parse()?,
    OpenPgpKeyUsageFlags::default(),
    &["Test <test@example.org>".parse()?],
    Default::default(),
    Timestamp::now(),
    OpenPgpVersion::V4,
)?;

// use the Administrator credentials to import the OpenPGP certificate as certificate for the key
nethsm.use_credentials(&"admin".parse()?)?;
assert!(nethsm.get_key_certificate(&"signing1".parse()?).is_err());
nethsm.import_key_certificate(&"signing1".parse()?, openpgp_cert)?;
assert!(nethsm.get_key_certificate(&"signing1".parse()?).is_ok());

pub fn get_key_certificate( &self, key_id: &KeyId, ) -> Result<Option<Vec<u8>>, Error>

Gets the certificate for a key.

Gets the certificate for a key identified by key_id and returns it as a byte vector. Returns None if no certificate is associated with a key identified by key_id.

This call requires using [Credentials] of a user in the [Operator][UserRole::Operator] or [Administrator][UserRole::Administrator] role.

Namespaces

• N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) are only able to get certificates for keys in their own namespace.
• R-Administrators (system-wide [Administrator][UserRole::Administrator] users) are only able to get certificates for system-wide keys.

Errors

Returns an Error::Api if getting the certificate for a key fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists
• the used [Credentials] are not correct
• the used [Credentials] are not those of a user in the [Operator][UserRole::Operator] or [Administrator][UserRole::Administrator] role

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    OpenPgpKeyUsageFlags,
    OpenPgpVersion,
    Passphrase,
    Timestamp,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator1".to_string(),
    UserRole::Operator,
    Passphrase::new("operator-passphrase".to_string()),
    Some("operator1".parse()?),
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;
// tag system-wide user in Operator role for access to signing key
nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;
// use the Operator credentials to create an OpenPGP certificate for a key
nethsm.use_credentials(&"operator1".parse()?)?;
let openpgp_cert = nethsm.create_openpgp_cert(
    &"signing1".parse()?,
    OpenPgpKeyUsageFlags::default(),
    &["Test <test@example.org>".parse()?],
    Default::default(),
    Timestamp::now(),
    OpenPgpVersion::V4,
)?;
// use the Administrator credentials to import the OpenPGP certificate as certificate for the key
nethsm.use_credentials(&"admin".parse()?)?;
nethsm.import_key_certificate(&"signing1".parse()?, openpgp_cert)?;

// get the certificate associated with a key
println!("{:?}", nethsm.get_key_certificate(&"signing1".parse()?)?);

pub fn delete_key_certificate(&self, key_id: &KeyId) -> Result<(), Error>

Deletes the certificate for a key.

Deletes the certificate for a key identified by key_id.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) are only able to delete certificates for keys in their own namespace.
• R-Administrators (system-wide [Administrator][UserRole::Administrator] users) are only able to delete certificates for system-wide keys.

Errors

Returns an Error::Api if deleting the certificate for a key fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists
• no certificate is associated with the key
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    OpenPgpKeyUsageFlags,
    OpenPgpVersion,
    Passphrase,
    Timestamp,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator1".to_string(),
    UserRole::Operator,
    Passphrase::new("operator-passphrase".to_string()),
    Some("operator1".parse()?),
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;
// tag system-wide user in Operator role for access to signing key
nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;
// use the Operator credentials to create an OpenPGP certificate for a key
nethsm.use_credentials(&"operator1".parse()?)?;
let openpgp_cert = nethsm.create_openpgp_cert(
    &"signing1".parse()?,
    OpenPgpKeyUsageFlags::default(),
    &["Test <test@example.org>".parse()?],
    Default::default(),
    Timestamp::now(),
    OpenPgpVersion::V4,
)?;
// use the Administrator credentials to import the OpenPGP certificate as certificate for the key
nethsm.use_credentials(&"admin".parse()?)?;
nethsm.import_key_certificate(&"signing1".parse()?, openpgp_cert)?;

// delete a certificate for a key with Key ID "signing1"
assert!(nethsm.delete_key_certificate(&"signing1".parse()?).is_ok());
nethsm.delete_key_certificate(&"signing1".parse()?)?;
assert!(nethsm.delete_key_certificate(&"signing1".parse()?).is_err());

pub fn get_key_csr( &self, key_id: &KeyId, distinguished_name: DistinguishedName, ) -> Result<String, Error>

Gets a Certificate Signing Request for a key.

Returns a Certificate Signing Request (CSR) for a key, identified by key_id in PKCS#10 format based on a provided [DistinguishedName].

This call requires using [Credentials] of a user in the [Operator][UserRole::Operator] or [Administrator][UserRole::Administrator] role.

Namespaces

• Users in a namespace only have access to keys in their own namespace
• System-wide users only have access to system-wide keys (not in a namespace).

Errors

Returns an Error::Api if getting a CSR for a key fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists
• the used [Credentials] are not correct
• the used [Credentials] are not those of a user in the [Operator][UserRole::Operator] or [Administrator][UserRole::Administrator] role

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    DistinguishedName,
    KeyMechanism,
    KeyType,
    NetHsm,
    Passphrase,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;

// get a CSR for a key
println!(
    "{}",
    nethsm.get_key_csr(
        &"signing1".parse()?,
        DistinguishedName {
            country_name: Some("DE".to_string()),
            state_or_province_name: Some("Berlin".to_string()),
            locality_name: Some("Berlin".to_string()),
            organization_name: Some("Foobar Inc".to_string()),
            organizational_unit_name: Some("Department of Foo".to_string()),
            common_name: "Foobar Inc".to_string(),
            email_address: Some("foobar@mcfooface.com".to_string()),
        }
    )?
);

pub fn sign_digest( &self, key_id: &KeyId, signature_type: SignatureType, digest: &[u8], ) -> Result<Vec<u8>, Error>

Signs a digest using a key.

Signs a digest using a key identified by key_id.

NOTE: This function offers low-level access for signing digests. Use sign for signing a message.

The digest must be of appropriate type depending on signature_type:

• SignatureType::Pkcs1, SignatureType::PssSha256 and SignatureType::EcdsaP256 require a SHA-256 digest
• SignatureType::PssSha1 requires a SHA-1 digest
• SignatureType::PssSha384 and SignatureType::EcdsaP384 require a SHA-384 digest
• SignatureType::PssSha512 and SignatureType::EcdsaP521 require a SHA-521 digest
• SignatureType::EdDsa requires no digest (digest is the message)

The returned data depends on the chosen SignatureType:

• SignatureType::Pkcs1 returns the PKCS 1 padded signature (no signature algorithm OID prepended, since the used hash is not known).
• SignatureType::PssSha1, SignatureType::PssSha224, SignatureType::PssSha256, SignatureType::PssSha384 and SignatureType::PssSha512 return the EMSA-PSS encoded signature.
• SignatureType::EdDsa returns the encoding as specified in RFC 8032 (5.1.6) (r appended with s (each 32 bytes), in total 64 bytes).
• SignatureType::EcdsaP256, SignatureType::EcdsaP384 and SignatureType::EcdsaP521 return the ASN.1 DER encoded signature (a sequence of integer r and integer s).

This call requires using [Credentials] of a user in the [Operator][UserRole::Operator] role, which carries a tag (see add_user_tag) matching one of the tags of the targeted key (see add_key_tag).

Namespaces

• [Operator][UserRole::Operator] users in a namespace only have access to keys in their own namespace.
• System-wide [Operator][UserRole::Operator] users only have access to system-wide keys.

Errors

Returns an Error::Api if signing the digest fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists on the NetHSM
• the chosen SignatureType is incompatible with the targeted key
• the chosen digest is incompatible with the SignatureType
• the [Operator][UserRole::Operator] user does not have access to the key (e.g. different namespace)
• the [Operator][UserRole::Operator] user does not carry a tag matching one of the key tags
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Operator][UserRole::Operator] role

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    Passphrase,
    SignatureType,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator1".to_string(),
    UserRole::Operator,
    Passphrase::new("operator-passphrase".to_string()),
    Some("operator1".parse()?),
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;
// tag system-wide user in Operator role for access to signing key
nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;

// create an ed25519 signature
nethsm.use_credentials(&"operator1".parse()?)?;
println!(
    "{:?}",
    nethsm.sign_digest(&"signing1".parse()?, SignatureType::EdDsa, &[0, 1, 2])?
);

pub fn sign( &self, key_id: &KeyId, signature_type: SignatureType, message: &[u8], ) -> Result<Vec<u8>, Error>

Signs a message using a key.

Signs a message using a key identified by key_id based on a specific signature_type.

The message should not be hashed, as this function takes care of it based on the provided SignatureType. For lower level access, see sign_digest.

The returned data depends on the chosen SignatureType:

• SignatureType::Pkcs1 returns the PKCS 1 padded signature (no signature algorithm OID prepended, since the used hash is not known).
• SignatureType::PssSha1, SignatureType::PssSha224, SignatureType::PssSha256, SignatureType::PssSha384 and SignatureType::PssSha512 return the EMSA-PSS encoded signature.
• SignatureType::EdDsa returns the encoding as specified in RFC 8032 (5.1.6) (r appended with s (each 32 bytes), in total 64 bytes).
• SignatureType::EcdsaP256, SignatureType::EcdsaP384 and SignatureType::EcdsaP521 return the ASN.1 DER encoded signature (a sequence of integer r and integer s).

This call requires using [Credentials] of a user in the [Operator][UserRole::Operator] role, which carries a tag (see add_user_tag) matching one of the tags of the targeted key (see add_key_tag).

Namespaces

• [Operator][UserRole::Operator] users in a namespace only have access to keys in their own namespace.
• System-wide [Operator][UserRole::Operator] users only have access to system-wide keys.

Errors

Returns an Error::Api if signing the message fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists on the NetHSM
• the chosen SignatureType is incompatible with the targeted key
• the [Operator][UserRole::Operator] user does not have access to the key (e.g. different namespace)
• the [Operator][UserRole::Operator] user does not carry a tag matching one of the key tags
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Operator][UserRole::Operator] role

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    Passphrase,
    SignatureType,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator1".to_string(),
    UserRole::Operator,
    Passphrase::new("operator-passphrase".to_string()),
    Some("operator1".parse()?),
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;
// tag system-wide user in Operator role for access to signing key
nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;

// create an ed25519 signature
println!(
    "{:?}",
    nethsm.sign(&"signing1".parse()?, SignatureType::EdDsa, b"message")?
);

pub fn encrypt( &self, key_id: &KeyId, mode: EncryptMode, message: &[u8], iv: Option<&[u8]>, ) -> Result<Vec<u8>, Error>

Encrypts a message using a symmetric key.

Encrypts a message using a symmetric key identified by key_id, a specific EncryptMode mode and initialization vector iv.

The targeted key must be of type KeyType::Generic and feature the mechanisms KeyMechanism::AesDecryptionCbc and KeyMechanism::AesEncryptionCbc.

This call requires using [Credentials] of a user in the [Operator][UserRole::Operator] role, which carries a tag (see add_user_tag) matching one of the tags of the targeted key (see add_key_tag).

Namespaces

• [Operator][UserRole::Operator] users in a namespace only have access to keys in their own namespace.
• System-wide [Operator][UserRole::Operator] users only have access to system-wide keys.

Errors

Returns an Error::Api if encrypting the message fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists on the NetHSM
• the chosen mode is incompatible with the targeted key
• the [Operator][UserRole::Operator] user does not have access to the key (e.g. different namespace)
• the [Operator][UserRole::Operator] user does not carry a tag matching one of the key tags
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Operator][UserRole::Operator] role

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    EncryptMode,
    KeyMechanism,
    KeyType,
    NetHsm,
    Passphrase,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator1".to_string(),
    UserRole::Operator,
    Passphrase::new("operator-passphrase".to_string()),
    Some("operator1".parse()?),
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Generic,
    vec![KeyMechanism::AesDecryptionCbc, KeyMechanism::AesEncryptionCbc],
    Some(128),
    Some("encryption1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;
// tag system-wide user in Operator role for access to signing key
nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;

// assuming we have an AES128 encryption key, the message must be a multiple of 32 bytes long
let message = b"Hello World! This is a message!!";
// we have an AES128 encryption key. the initialization vector must be a multiple of 16 bytes long
let iv = b"This is unsafe!!";

// encrypt message using
println!(
    "{:?}",
    nethsm.encrypt(&"encryption1".parse()?, EncryptMode::AesCbc, message, Some(iv))?
);

pub fn decrypt( &self, key_id: &KeyId, mode: DecryptMode, message: &[u8], iv: Option<&[u8]>, ) -> Result<Vec<u8>, Error>

Decrypts a message using a key.

Decrypts a message using a key identified by key_id, a specific DecryptMode mode and initialization vector iv.

This function can be used to decrypt messages encrypted using a symmetric key (e.g. using encrypt) by providing DecryptMode::AesCbc as mode. The targeted key must be of type KeyType::Generic and feature the mechanisms KeyMechanism::AesDecryptionCbc and KeyMechanism::AesEncryptionCbc.

Decryption for messages encrypted using an asymmetric key is also possible. Foreign entities can use the public key of an asymmetric key (see get_public_key) to encrypt a message and the private key on the NetHSM is used for decryption.

This call requires using [Credentials] of a user in the [Operator][UserRole::Operator] role, which carries a tag (see add_user_tag) matching one of the tags of the targeted key (see add_key_tag).

Namespaces

• [Operator][UserRole::Operator] users in a namespace only have access to keys in their own namespace.
• System-wide [Operator][UserRole::Operator] users only have access to system-wide keys.

Errors

Returns an Error::Api if decrypting the message fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists on the NetHSM
• the chosen mode is incompatible with the targeted key
• the encrypted message can not be decrypted
• the [Operator][UserRole::Operator] user does not have access to the key (e.g. different namespace)
• the [Operator][UserRole::Operator] user does not carry a tag matching one of the key tags
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Operator][UserRole::Operator] role

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    DecryptMode,
    EncryptMode,
    KeyMechanism,
    KeyType,
    NetHsm,
    Passphrase,
    UserRole
};
use rsa::{pkcs8::DecodePublicKey, Pkcs1v15Encrypt, RsaPublicKey};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator1".to_string(),
    UserRole::Operator,
    Passphrase::new("operator-passphrase".to_string()),
    Some("operator1".parse()?),
)?;
// generate system-wide keys with the same tag
nethsm.generate_key(
    KeyType::Generic,
    vec![KeyMechanism::AesDecryptionCbc, KeyMechanism::AesEncryptionCbc],
    Some(128),
    Some("encryption1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;
nethsm.generate_key(
    KeyType::Rsa,
    vec![KeyMechanism::RsaDecryptionPkcs1],
    None,
    Some("encryption2".parse()?),
    Some(vec!["tag1".to_string()]),
)?;
// tag system-wide user in Operator role for access to signing key
nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;

// assuming we have an AES128 encryption key, the message must be a multiple of 32 bytes long
let message = "Hello World! This is a message!!".to_string();
// we have an AES128 encryption key. the initialization vector must be a multiple of 16 bytes long
let iv = "This is unsafe!!".to_string();

// encrypt message using a symmetric key
nethsm.use_credentials(&"operator1".parse()?)?;
let encrypted_message = nethsm.encrypt(&"encryption1".parse()?, EncryptMode::AesCbc, message.as_bytes(), Some(iv.as_bytes()))?;

// decrypt message using the same symmetric key and the same initialization vector
assert_eq!(
    message.as_bytes(),
    &nethsm.decrypt(&"encryption1".parse()?, DecryptMode::AesCbc, &encrypted_message, Some(iv.as_bytes()))?
);

// get the public key of an asymmetric key and encrypt the message with it
let pubkey = RsaPublicKey::from_public_key_pem(&nethsm.get_public_key(&"encryption2".parse()?)?)?;
let mut rng = rand::thread_rng();
let encrypted_message = pubkey.encrypt(&mut rng, Pkcs1v15Encrypt, message.as_bytes())?;
println!("raw encrypted message: {:?}", encrypted_message);

let decrypted_message =
    nethsm.decrypt(&"encryption2".parse()?, DecryptMode::Pkcs1, &encrypted_message, None)?;
println!("raw decrypted message: {:?}", decrypted_message);

assert_eq!(&decrypted_message, message.as_bytes());

impl NetHsm

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

Returns whether the NetHSM is in [Unprovisioned][SystemState::Unprovisioned] or [Locked][SystemState::Locked] state.

For this call no [Credentials] are required and if any are configured, they are ignored.

Errors

Returns an Error::Api if the information can not be retrieved or the NetHSM is in [Operational][SystemState::Operational] state.

Examples

use nethsm::{Connection, ConnectionSecurity, NetHsm};

// no initial credentials are required
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    None,
    None,
    None,
)?;

// check whether the NetHSM is locked or unprovisioned
assert!(nethsm.alive().is_ok());

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

Returns whether the NetHSM is in [Operational][SystemState::Operational] state.

For this call no [Credentials] are required and if any are configured, they are ignored.

Errors

Returns an Error::Api if the information can not be retrieved or the NetHSM is in [Unprovisioned][SystemState::Unprovisioned] or [Locked][SystemState::Locked] state.

Examples

use nethsm::{Connection, ConnectionSecurity, NetHsm};

// no initial credentials are required
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    None,
    None,
    None,
)?;

// check whether the NetHSM is operational
assert!(nethsm.ready().is_ok());

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

Returns the system state of the NetHSM.

Returns a variant of [SystemState], which describes the state a NetHSM is currently in.

For this call no [Credentials] are required and if any are configured, they are ignored.

Errors

Returns an Error::Api if the state information can not be retrieved.

Examples

use nethsm::{Connection, ConnectionSecurity, NetHsm};

// no initial credentials are required
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    None,
    None,
    None,
)?;

// retrieve the state
println!("{:?}", nethsm.state()?);

pub fn info(&self) -> Result<InfoData, Error>

Returns device information for the NetHSM.

Returns an [InfoData], which provides the device information.

For this call no [Credentials] are required and if any are configured, they are ignored.

Errors

Returns an Error::Api if the NetHSM device information can not be retrieved.

Examples

use nethsm::{Connection, ConnectionSecurity, NetHsm};

// no initial credentials are required
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    None,
    None,
    None,
)?;

// retrieve the NetHSM info
println!("{:?}", nethsm.info()?);

impl NetHsm

pub fn create_openpgp_cert<'notation_name, 'notation_value>( &self, key_id: &KeyId, flags: OpenPgpKeyUsageFlags, user_ids: &[OpenPgpUserId], notations: &[Notation<'notation_name, 'notation_value>], created_at: Timestamp, version: OpenPgpVersion, ) -> Result<Vec<u8>, Error>

Creates an OpenPGP certificate for an existing key.

The NetHSM key identified by key_id is used to issue required binding signatures (e.g. those for the User ID defined by user_id). Using flags it is possible to define the key’s capabilities and with created_at to provide the certificate’s creation time. Using version the OpenPGP version is provided (currently only OpenPgpVersion::V4 is supported). The resulting OpenPGP certificate is returned as vector of bytes.

To make use of the OpenPGP certificate (e.g. with openpgp_sign), it should be added as certificate for the key using import_key_certificate.

This call requires using a user in the [Operator][UserRole::Operator] role, which carries a tag (see add_user_tag) matching one of the tags of the targeted key (see add_key_tag).

Namespaces

• [Operator][UserRole::Operator] users in a namespace only have access to keys in their own namespace.
• System-wide [Operator][UserRole::Operator] users only have access to system-wide keys.

Errors

Returns an Error::Api if creating an OpenPGP certificate for a key fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists on the NetHSM
• the [Operator][UserRole::Operator] user does not have access to the key (e.g. different namespace)
• the [Operator][UserRole::Operator] user does not carry a tag matching one of the key tags
• the used [Credentials] are not correct
• the used [Credentials] are not those of a user in the [Operator][UserRole::Operator] role

Panics

Panics if the currently unimplemented OpenPgpVersion::V6 is provided as version.

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    OpenPgpKeyUsageFlags,
    OpenPgpVersion,
    Passphrase,
    Timestamp,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator1".to_string(),
    UserRole::Operator,
    Passphrase::new("operator-passphrase".to_string()),
    Some("operator1".parse()?),
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;
// tag system-wide user in Operator role for access to signing key
nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;

// create an OpenPGP certificate for the key with ID "signing1"
nethsm.use_credentials(&"operator1".parse()?)?;
assert!(
    !nethsm
        .create_openpgp_cert(
            &"signing1".parse()?,
            OpenPgpKeyUsageFlags::default(),
            &["Test <test@example.org>".parse()?],
            Default::default(),
            Timestamp::now(),
            OpenPgpVersion::V4,
        )?
        .is_empty()
);

pub fn openpgp_sign( &self, key_id: &KeyId, message: &[u8], ) -> Result<Vec<u8>, Error>

Creates an OpenPGP signature for a message.

Signs the message using the key identified by key_id and returns a binary OpenPGP data signature.

This call requires using a user in the [Operator][UserRole::Operator] role, which carries a tag (see add_user_tag) matching one of the tags of the targeted key (see add_key_tag).

Namespaces

• [Operator][UserRole::Operator] users in a namespace only have access to keys in their own namespace.
• System-wide [Operator][UserRole::Operator] users only have access to system-wide keys.

Errors

Returns an Error::Api if creating an OpenPGP signature for the message fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists on the NetHSM
• the [Operator][UserRole::Operator] user does not have access to the key (e.g. different namespace)
• the [Operator][UserRole::Operator] user does not carry a tag matching one of the key tags
• the used [Credentials] are not correct
• the used [Credentials] are not those of a user in the [Operator][UserRole::Operator] role

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    OpenPgpKeyUsageFlags,
    OpenPgpVersion,
    Passphrase,
    Timestamp,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator1".to_string(),
    UserRole::Operator,
    Passphrase::new("operator-passphrase".to_string()),
    Some("operator1".parse()?),
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;
// tag system-wide user in Operator role for access to signing key
nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;
// create an OpenPGP certificate for the key with ID "signing1"
nethsm.use_credentials(&"operator1".parse()?)?;
let openpgp_cert = nethsm.create_openpgp_cert(
    &"signing1".parse()?,
    OpenPgpKeyUsageFlags::default(),
    &["Test <test@example.org>".parse()?],
    Default::default(),
    Timestamp::now(),
    OpenPgpVersion::V4,
)?;
// import the OpenPGP certificate as key certificate
nethsm.use_credentials(&"admin".parse()?)?;
nethsm.import_key_certificate(&"signing1".parse()?, openpgp_cert)?;

// create OpenPGP signature
nethsm.use_credentials(&"operator1".parse()?)?;
assert!(
    !nethsm
        .openpgp_sign(&"signing1".parse()?, b"sample message")?
        .is_empty()
);

pub fn openpgp_sign_state( &self, key_id: &KeyId, state: Sha512, ) -> Result<String, Error>

Generates an armored OpenPGP signature based on provided hasher state.

Signs the hasher state using the key identified by key_id and returns a binary OpenPGP data signature.

This call requires using a user in the [Operator][UserRole::Operator] role, which carries a tag (see add_user_tag) matching one of the tags of the targeted key (see add_key_tag).

Namespaces

• [Operator][UserRole::Operator] users in a namespace only have access to keys in their own namespace.
• System-wide [Operator][UserRole::Operator] users only have access to system-wide keys.

Errors

Returns an Error::Api if creating an OpenPGP signature for the hasher state fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• no key identified by key_id exists on the NetHSM
• the [Operator][UserRole::Operator] user does not have access to the key (e.g. different namespace)
• the [Operator][UserRole::Operator] user does not carry a tag matching one of the key tags
• the used [Credentials] are not correct
• the used [Credentials] are not those of a user in the [Operator][UserRole::Operator] role

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    OpenPgpKeyUsageFlags,
    OpenPgpVersion,
    Passphrase,
    Timestamp,
    UserRole,
};
use sha2::{Digest, Sha512};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator1".to_string(),
    UserRole::Operator,
    Passphrase::new("operator-passphrase".to_string()),
    Some("operator1".parse()?),
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;
// tag system-wide user in Operator role for access to signing key
nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;
// create an OpenPGP certificate for the key with ID "signing1"
nethsm.use_credentials(&"operator1".parse()?)?;
let openpgp_cert = nethsm.create_openpgp_cert(
    &"signing1".parse()?,
    OpenPgpKeyUsageFlags::default(),
    &["Test <test@example.org>".parse()?],
    Default::default(),
    Timestamp::now(),
    OpenPgpVersion::V4,
)?;
// import the OpenPGP certificate as key certificate
nethsm.use_credentials(&"admin".parse()?)?;
nethsm.import_key_certificate(&"signing1".parse()?, openpgp_cert)?;

let mut state = Sha512::new();
state.update(b"Hello world!");

// create OpenPGP signature
nethsm.use_credentials(&"operator1".parse()?)?;
assert!(
    !nethsm
        .openpgp_sign_state(&"signing1".parse()?, state)?
        .is_empty()
);

impl NetHsm

pub fn provision( &self, unlock_passphrase: Passphrase, admin_passphrase: Passphrase, system_time: DateTime<Utc>, ) -> Result<(), Error>

Provisions a NetHSM.

Provisioning is the initial setup step for a NetHSM. It sets the unlock_passphrase, which is used to unlock a device in [Locked][SystemState::Locked] state, the initial admin_passphrase for the default [Administrator][UserRole::Administrator] account (“admin”) and the system_time. The unlock passphrase can later on be changed using set_unlock_passphrase and the admin passphrase using set_user_passphrase.

For this call no [Credentials] are required and if any are configured, they are ignored.

Errors

Returns an Error::Api if provisioning fails:

• the NetHSM is not in [Unprovisioned][SystemState::Unprovisioned] state
• the provided data is malformed

Examples

use chrono::Utc;
use nethsm::{Connection, ConnectionSecurity, NetHsm, Passphrase};

// no initial credentials are required
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    None,
    None,
    None,
)?;

// provision the NetHSM
nethsm.provision(
    Passphrase::new("unlock-the-device".to_string()),
    Passphrase::new("admin-passphrase".to_string()),
    Utc::now(),
)?;

pub fn metrics(&self) -> Result<Value, Error>

Returns metrics for the NetHSM.

Returns a Value which provides metrics for the NetHSM.

This call requires using [Credentials] of a user in the [Metrics][UserRole::Metrics] role.

Errors

Returns an Error::Api if the NetHSM metrics can not be retrieved:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Metrics][UserRole::Metrics] role

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase};

// create a connection with a system-wide user in the Metrics role
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "metrics".parse()?,
        Some(Passphrase::new("metrics-passphrase".to_string())),
    )),
    None,
    None,
)?;

// retrieve the metrics
println!("{:?}", nethsm.metrics()?);

pub fn set_unlock_passphrase( &self, current_passphrase: Passphrase, new_passphrase: Passphrase, ) -> Result<(), Error>

Sets the unlock passphrase.

Changes the unlock passphrase from current_passphrase to new_passphrase.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if the unlock passphrase can not be changed:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the provided current_passphrase is not correct
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can set the unlock passphrase
nethsm.set_unlock_passphrase(
    Passphrase::new("current-unlock-passphrase".to_string()),
    Passphrase::new("new-unlock-passphrase".to_string()),
)?;

// N-Administrators can not set the unlock passphrase
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(
    nethsm
        .set_unlock_passphrase(
            Passphrase::new("current-unlock-passphrase".to_string()),
            Passphrase::new("new-unlock-passphrase".to_string()),
        )
        .is_err()
);

pub fn get_boot_mode(&self) -> Result<BootMode, Error>

Returns the boot mode.

Returns a variant of [BootMode] which represents the NetHSM’s boot mode.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if the boot mode can not be retrieved:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can retrieve the boot mode
println!("{:?}", nethsm.get_boot_mode()?);

// N-Administrators can not retrieve the boot mode
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.get_boot_mode().is_err());

pub fn set_boot_mode(&self, boot_mode: BootMode) -> Result<(), Error>

Sets the boot mode.

Sets the NetHSM’s boot mode based on a [BootMode] variant.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if the boot mode can not be set:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{
    BootMode,
    Connection,
    ConnectionSecurity,
    Credentials,
    NetHsm,
    Passphrase,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can set the boot mode
// set the boot mode to unattended
nethsm.set_boot_mode(BootMode::Unattended)?;
// set the boot mode to attended
nethsm.set_boot_mode(BootMode::Attended)?;

// N-Administrators can not set the boot mode
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.set_boot_mode(BootMode::Attended).is_err());

pub fn get_tls_public_key(&self) -> Result<String, Error>

Returns the TLS public key of the API.

Returns the NetHSM’s public key part of its TLS certificate which is used for communication with the API.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if the NetHSM’s TLS public key can not be retrieved:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can get the TLS public key
println!("{}", nethsm.get_tls_public_key()?);

// N-Administrators can not get the TLS public key
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.get_tls_public_key().is_err());

pub fn get_tls_cert(&self) -> Result<String, Error>

Returns the TLS certificate of the API.

Returns the NetHSM’s TLS certificate which is used for communication with the API.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if the NetHSM’s TLS certificate can not be retrieved:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can get the TLS certificate
println!("{}", nethsm.get_tls_cert()?);

// N-Administrators can not get the TLS certificate
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.get_tls_cert().is_err());

pub fn get_tls_csr( &self, distinguished_name: DistinguishedName, ) -> Result<String, Error>

Returns a Certificate Signing Request (CSR) for the API’s TLS certificate.

Based on [DistinguishedName] data returns a CSR in PKCS#10 format for the NetHSM’s TLS certificate.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if the CSR can not be retrieved:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    DistinguishedName,
    NetHsm,
    Passphrase,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can get a CSR for the TLS certificate
println!(
    "{}",
    nethsm.get_tls_csr(DistinguishedName {
        country_name: Some("DE".to_string()),
        state_or_province_name: Some("Berlin".to_string()),
        locality_name: Some("Berlin".to_string()),
        organization_name: Some("Foobar Inc".to_string()),
        organizational_unit_name: Some("Department of Foo".to_string()),
        common_name: "Foobar Inc".to_string(),
        email_address: Some("foobar@mcfooface.com".to_string()),
    })?
);

// N-Administrators can not get a CSR for the TLS certificate
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(
    nethsm
        .get_tls_csr(DistinguishedName {
            country_name: Some("DE".to_string()),
            state_or_province_name: Some("Berlin".to_string()),
            locality_name: Some("Berlin".to_string()),
            organization_name: Some("Foobar Inc".to_string()),
            organizational_unit_name: Some("Department of Foo".to_string()),
            common_name: "Foobar Inc".to_string(),
            email_address: Some("foobar@mcfooface.com".to_string()),
        })
        .is_err()
);

pub fn generate_tls_cert( &self, tls_key_type: TlsKeyType, length: Option<u32>, ) -> Result<(), Error>

Generates a new TLS certificate for the API.

Generates a new TLS certificate (used for communication with the API) based on tls_key_type and length.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if the new TLS certificate can not be generated:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the tls_key_type and length combination is not valid
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    NetHsm,
    Passphrase,
    TlsKeyType,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can generate a new TLS certificate
nethsm.generate_tls_cert(TlsKeyType::Rsa, Some(4096))?;

// N-Administrators can not generate a new TLS certificate
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(
    nethsm
        .generate_tls_cert(TlsKeyType::Rsa, Some(4096))
        .is_err()
);

pub fn set_tls_cert(&self, certificate: &str) -> Result<(), Error>

Sets a new TLS certificate for the API.

Accepts a Base64 encoded DER certificate provided using certificate which is added as new TLS certificate for communication with the API.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if setting a new TLS certificate fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the provided certificate is not valid
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

let cert = r#"-----BEGIN CERTIFICATE-----
MIIBHjCBxKADAgECAghDngCv6xWIXDAKBggqhkjOPQQDAjAUMRIwEAYDVQQDDAlr
ZXlmZW5kZXIwIBcNNzAwMTAxMDAwMDAwWhgPOTk5OTEyMzEyMzU5NTlaMBQxEjAQ
BgNVBAMMCWtleWZlbmRlcjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABJsHIrsZ
6fJzrk12GK7nW6bGyTIIZiQUq0uaKbn21dgPiDCO5+iYVXAqnWu4IMVZQnkFJmte
PRUUuM3119f8ffkwCgYIKoZIzj0EAwIDSQAwRgIhALH4fDYJ21tRecXp9IipBlil
p+hJCj77zBvFmGYy/UnPAiEA8csj7U6BfzvK4EiQyUZa7/as+nXwj3XHU/i8LyLm
Chw=
-----END CERTIFICATE-----"#;

// R-Administrators can set a new TLS certificate
nethsm.set_tls_cert(cert)?;

// N-Administrators can not set a new TLS certificate
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.set_tls_cert(cert).is_err());

pub fn get_network(&self) -> Result<NetworkConfig, Error>

Gets the network configuration.

Retrieves the network configuration of the NetHSM as [NetworkConfig].

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if retrieving network configuration fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can get the network configuration
println!("{:?}", nethsm.get_network()?);

// N-Administrators can not get the network configuration
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.get_network().is_err());

pub fn set_network(&self, network_config: NetworkConfig) -> Result<(), Error>

Sets the network configuration.

Sets the network configuration of the NetHSM on the basis of a [NetworkConfig].

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if setting the network configuration fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the provided network_config is not valid
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    NetHsm,
    NetworkConfig,
    Passphrase,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

let network_config = NetworkConfig::new(
    "192.168.1.1".to_string(),
    "255.255.255.0".to_string(),
    "0.0.0.0".to_string(),
);

// R-Administrators can set the network configuration
nethsm.set_network(network_config.clone())?;

// N-Administrators can not set the network configuration
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.set_network(network_config).is_err());

pub fn get_time(&self) -> Result<String, Error>

Gets the current time.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if retrieving time fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can get the time
println!("{:?}", nethsm.get_time()?);

// N-Administrators can not get the time
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.get_time().is_err());

pub fn set_time(&self, time: DateTime<Utc>) -> Result<(), Error>

Sets the current time.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if setting time fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the provided time is not valid
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use chrono::Utc;
use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can set the time
nethsm.set_time(Utc::now())?;

// N-Administrators can not set the time
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.set_time(Utc::now()).is_err());

pub fn get_logging(&self) -> Result<LoggingConfig, Error>

Gets the logging configuration.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if getting the logging configuration fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can get logging configuration
println!("{:?}", nethsm.get_logging()?);

// N-Administrators can not get logging configuration
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.get_logging().is_err());

pub fn set_logging( &self, ip_address: Ipv4Addr, port: u32, log_level: LogLevel, ) -> Result<(), Error>

Sets the logging configuration.

Sets the NetHSM’s logging configuration by providing ip_address and port of a host to send logs to. The log level is configured using log_level.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if setting the logging configuration fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the provided ip_address, port or log_level are not valid
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use std::net::Ipv4Addr;

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    LogLevel,
    NetHsm,
    Passphrase,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can set logging configuration
nethsm.set_logging(Ipv4Addr::new(192, 168, 1, 2), 513, LogLevel::Debug)?;

// N-Administrators can not set logging configuration
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(
    nethsm
        .set_logging(Ipv4Addr::new(192, 168, 1, 2), 513, LogLevel::Debug)
        .is_err()
);

pub fn set_backup_passphrase( &self, current_passphrase: Passphrase, new_passphrase: Passphrase, ) -> Result<(), Error>

Sets the backup passphrase.

Sets current_passphrase to new_passphrase, which changes the backup passphrase for the NetHSM.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if setting the backup passphrase fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the provided current_passphrase is not correct
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can set the backup passphrase
nethsm.set_backup_passphrase(
    Passphrase::new("current-backup-passphrase".to_string()),
    Passphrase::new("new-backup-passphrase".to_string()),
)?;

// N-Administrators can not set logging configuration
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(
    nethsm
        .set_backup_passphrase(
            Passphrase::new("new-backup-passphrase".to_string()),
            Passphrase::new("current-backup-passphrase".to_string()),
        )
        .is_err()
);

pub fn backup(&self) -> Result<Vec<u8>, Error>

Creates a backup.

Triggers the creation and download of a backup of the NetHSM. NOTE: Before creating the first backup, the backup passphrase must be set using set_backup_passphrase.

This call requires using [Credentials] of a user in the [Backup][UserRole::Backup] role.

Errors

Returns an Error::Api if creating a backup fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Backup][UserRole::Backup] role
• the backup passphrase has not yet been set

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase};

// create a connection with a user in the Backup role
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "backup1".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// create a backup and write it to file
std::fs::write("nethsm.bkp", nethsm.backup()?)?;

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

Triggers a factory reset.

Triggers a factory reset of the NetHSM. WARNING: This action deletes all user and system data! Make sure to create a backup using backup first!

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if resetting the NetHSM fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    NetHsm,
    Passphrase,
    SystemState,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// N-Administrators can not trigger factory reset
assert_eq!(nethsm.state()?, SystemState::Operational);
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.factory_reset().is_err());

// R-Administrators are able to trigger a factory reset
assert_eq!(nethsm.state()?, SystemState::Operational);
nethsm.use_credentials(&"admin".parse()?)?;
nethsm.factory_reset()?;
assert_eq!(nethsm.state()?, SystemState::Unprovisioned);

pub fn restore( &self, backup_passphrase: Passphrase, system_time: DateTime<Utc>, backup: Vec<u8>, ) -> Result<(), Error>

Restores NetHSM from backup.

Restores a NetHSM from a backup, by providing a backup_passphrase (see set_backup_passphrase) a new system_time for the NetHSM and a backup file (created using backup).

The NetHSM must be in [Operational][SystemState::Operational] or [Unprovisioned][SystemState::Unprovisioned] state.

Any existing user data is safely removed and replaced by that of the backup, after which the NetHSM ends up in [Locked][SystemState::Locked] state. If the NetHSM is in [Unprovisioned][SystemState::Unprovisioned] state, additionally the system configuration from the backup is applied and leads to a reboot of the NetHSM.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if restoring the NetHSM from backup fails:

• the NetHSM is not in [Operational][SystemState::Operational] or [Unprovisioned][SystemState::Unprovisioned] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use chrono::Utc;
use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// N-Administrators can not restore from backup
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(
    nethsm
        .restore(
            Passphrase::new("backup-passphrase".to_string()),
            Utc::now(),
            std::fs::read("nethsm.bkp")?,
        )
        .is_err()
);

// R-Administrators can restore from backup
nethsm.use_credentials(&"admin".parse()?)?;
nethsm.restore(
    Passphrase::new("backup-passphrase".to_string()),
    Utc::now(),
    std::fs::read("nethsm.bkp")?,
)?;

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

Locks the NetHSM.

Locks the NetHSM and sets its state to [Locked][SystemState::Locked].

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if locking the NetHSM fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    NetHsm,
    Passphrase,
    SystemState,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

assert_eq!(nethsm.state()?, SystemState::Operational);

// N-Administrators can not lock the NetHSM
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.lock().is_err());

// R-Administrators can lock the NetHSM
nethsm.use_credentials(&"admin".parse()?)?;
nethsm.lock()?;
assert_eq!(nethsm.state()?, SystemState::Locked);

pub fn unlock(&self, unlock_passphrase: Passphrase) -> Result<(), Error>

Unlocks the NetHSM.

Unlocks the NetHSM if it is in [Locked][SystemState::Locked] state by providing unlock_passphrase and sets its state to [Operational][SystemState::Operational].

For this call no [Credentials] are required and if any are configured, they are ignored.

Errors

Returns an Error::Api if unlocking the NetHSM fails:

• the NetHSM is not in [Locked][SystemState::Locked] state

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, SystemState};

// no initial [`Credentials`] are required
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    None,
    None,
    None,
)?;

assert_eq!(nethsm.state()?, SystemState::Locked);
// unlock the NetHSM
nethsm.unlock(Passphrase::new("unlock-passphrase".to_string()))?;
assert_eq!(nethsm.state()?, SystemState::Operational);

pub fn system_info(&self) -> Result<SystemInfo, Error>

Retrieves system information.

Returns system information in the form of a [SystemInfo], which contains various pieces of information such as software version, software build, firmware version, hardware version, device ID and information on TPM related components such as attestation key and relevant PCR values.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if retrieving the system information fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can retrieve system information
println!("{:?}", nethsm.system_info()?);

// N-Administrators can not retrieve system information
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.system_info().is_err());

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

Reboots the NetHSM.

Reboots the NetHSM, if it is in [Operational][SystemState::Operational] state.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if rebooting the NetHSM fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// N-Administrators can not reboot the NetHSM
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.reboot().is_err());

// R-Administrators can reboot the NetHSM
nethsm.use_credentials(&"admin".parse()?)?;
nethsm.reboot()?;

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

Shuts down the NetHSM.

Shuts down the NetHSM, if it is in [Operational][SystemState::Operational] state.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if shutting down the NetHSM fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// N-Administrators can not shut down the NetHSM
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.shutdown().is_err());

// R-Administrators can shut down the NetHSM
nethsm.use_credentials(&"admin".parse()?)?;
nethsm.shutdown()?;

pub fn upload_update(&self, update: Vec<u8>) -> Result<SystemUpdateData, Error>

Uploads a software update.

WARNING: This function has shown flaky behavior during tests with the official container! Upload may have to be repeated!

Uploads a software update to the NetHSM, if it is in [Operational][SystemState::Operational] state and returns information about the software update as [SystemUpdateData]. Software updates can successively be installed (commit_update) or canceled (cancel_update).

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if uploading the software update fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// N-Administrators can not upload software updates to the NetHSM
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.upload_update(std::fs::read("update.bin")?).is_err());

// R-Administrators can upload software updates to the NetHSM
nethsm.use_credentials(&"admin".parse()?)?;
println!("{:?}", nethsm.upload_update(std::fs::read("update.bin")?)?);

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

Commits an already uploaded software update.

Commits a software update previously uploaded to the NetHSM (using upload_update), if the NetHSM is in [Operational][SystemState::Operational] state. Successfully committing a software update leads to the reboot of the NetHSM.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if committing the software update fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• there is no software update to commit
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

println!("{:?}", nethsm.upload_update(std::fs::read("update.bin")?)?);

// N-Administrators can not commit software updates on a NetHSM
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.commit_update().is_err());

// R-Administrators can commit software updates on a NetHSM
nethsm.use_credentials(&"admin".parse()?)?;
nethsm.commit_update()?;

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

Cancels an already uploaded software update.

Cancels a software update previously uploaded to the NetHSM (using upload_update), if the NetHSM is in [Operational][SystemState::Operational] state.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if canceling the software update fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• there is no software update to cancel
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    NetHsm,
    Passphrase,
    SystemState,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

println!("{:?}", nethsm.upload_update(std::fs::read("update.bin")?)?);
assert_eq!(nethsm.state()?, SystemState::Operational);

// N-Administrators can not cancel software updates on a NetHSM
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.cancel_update().is_err());

// R-Administrators can cancel software updates on a NetHSM
nethsm.cancel_update()?;
assert_eq!(nethsm.state()?, SystemState::Operational);

pub fn random(&self, length: u32) -> Result<Vec<u8>, Error>

Generates random bytes.

Retrieves length random bytes from the NetHSM, if it is in [Operational][SystemState::Operational] state.

This call requires using [Credentials] of a user in the [Operator][UserRole::Operator] role.

Errors

Returns an Error::Api if retrieving random bytes fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Operator][UserRole::Operator] role

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator1".to_string(),
    UserRole::Operator,
    Passphrase::new("operator-passphrase".to_string()),
    Some("operator1".parse()?),
)?;
nethsm.use_credentials(&"operator1".parse()?)?;

// get 10 random bytes
println!("{:#?}", nethsm.random(10)?);

impl NetHsm

pub fn add_namespace(&self, namespace_id: &NamespaceId) -> Result<(), Error>

Adds a new namespace.

Adds a new namespace with the ID namespace_id.

WARNING: A user in the [Administrator][UserRole::Administrator] role must be added for the namespace using add_user before creating the namespace! Otherwise there is no user to administrate the new namespace!

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if adding the namespace fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the namespace identified by namespace_id exists already
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// N-Administrator can not create namespaces
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.add_namespace(&"namespace2".parse()?).is_err());

pub fn get_namespaces(&self) -> Result<Vec<NamespaceId>, Error>

Gets all available namespaces.

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if getting the namespaces fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// print list of all namespaces
println!("{:?}", nethsm.get_namespaces()?);

// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// N-Administrator can not get namespaces
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.get_namespaces().is_err());

pub fn delete_namespace(&self, namespace_id: &NamespaceId) -> Result<(), Error>

Deletes an existing namespace.

Deletes the namespace identified by namespace_id.

WARNING: This call deletes the namespace and all keys in it! Make sure to create a backup!

This call requires using [Credentials] of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator).

Errors

Returns an Error::Api if deleting the namespace fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the namespace identified by namespace_id does not exist
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide user in the [Administrator][UserRole::Administrator] role (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// create accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// N-Administrators can not delete namespaces
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.delete_namespace(&"namespace1".parse()?).is_err());

// R-Administrators can delete namespaces
nethsm.use_credentials(&"admin".parse()?)?;
nethsm.delete_namespace(&"namespace1".parse()?)?;

pub fn add_user( &self, real_name: String, role: UserRole, passphrase: Passphrase, user_id: Option<UserId>, ) -> Result<UserId, Error>

Adds a user and returns its User ID.

A new user is created by providing a real_name from which a User ID is derived (optionally a User ID can be provided with user_id), a role which describes the user’s access rights on the NetHSM (see [UserRole]) and a passphrase.

Internally, this function also calls add_credentials to add the new user to the list of available credentials.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role. When adding a user to a namespace, that does not yet exist, the caller must be a system-wide [Administrator][UserRole::Administrator] (R-Administrator). When adding a user to an already existing namespace, the caller must be an [Administrator][UserRole::Administrator] in that namespace (N-Administrator).

Namespaces

New users implicitly inherit the namespace of the caller. A namespace can be provided explicitly by prefixing the User ID with the ID of a namespace and the ~ character (e.g. namespace1~user1). When specifying a namespace as part of the User ID and the namespace exists already, the caller must be an [Administrator][UserRole::Administrator] of that namespace (N-Administrator). When specifying a namespace as part of the User ID and the namespace does not yet exist, the caller must be a system-wide [Administrator][UserRole::Administrator] (R-Administrator).

NOTE: Users in the [Backup][UserRole::Backup] and [Metrics][UserRole::Metrics] role can not be created for a namespace, as their underlying functionality can only be used in a system-wide context!

Errors

Returns an Error::Api if adding the user fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the provided real_name, passphrase or user_id are not valid
• the provided user_id exists already
• the used [Credentials] are not correct
• the used [Credentials] are not that of a system-wide [Administrator][UserRole::Administrator], when adding a user to a not yet existing namespace
• the used [Credentials] are not that of an [Administrator][UserRole::Administrator] in the namespace the user is about to be added to

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator One".to_string(),
    UserRole::Operator,
    Passphrase::new("operator1-passphrase".to_string()),
    Some("user1".parse()?),
)?;

// this fails because the user exists already
assert!(nethsm
    .add_user(
        "Operator One".to_string(),
        UserRole::Operator,
        Passphrase::new("operator1-passphrase".to_string()),
        Some("user1".parse()?),
    )
    .is_err());

// add a user in the Administrator role (N-Administrator) for a not yet existing namespace "namespace1"
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespace1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;

pub fn delete_user(&self, user_id: &UserId) -> Result<(), Error>

Deletes an existing user.

Deletes a user identified by user_id.

Internally, this function also calls remove_credentials to remove the user from the list of available credentials.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) can only delete users in their own namespace.
• R-Administrators (system-wide [Administrator][UserRole::Administrator] users) can only delete system-wide users, but not those in a namespace. To allow R-Administrators to delete users in a namespace, the given namespace has to be deleted first using delete_namespace.

Errors

Returns an Error::Api if deleting a user fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the user identified by user_id does not exist
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role
• the targeted user is in an existing namespace, but the caller is an R-Administrator or an N-Administrator in a different namespace
• the targeted user is a system-wide user, but the caller is not an R-Administrator
• the user attempts to delete itself

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator One".to_string(),
    UserRole::Operator,
    Passphrase::new("operator1-passphrase".to_string()),
    Some("user1".parse()?),
)?;

// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespce1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// add the accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// R-Administrators can not delete N-Administrators, as long as their namespace exists
assert!(nethsm.delete_user(&"namespace1~admin1".parse()?).is_err());
// however, after deleting the namespace, this becomes possible
nethsm.delete_namespace(&"namespace1".parse()?)?;
nethsm.delete_user(&"namespace1~admin1".parse()?)?;

// R-Administrators can delete system-wide users
nethsm.delete_user(&"user1".parse()?)?;

pub fn get_users(&self) -> Result<Vec<UserId>, Error>

Gets a list of all User IDs.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) can only list users in their own namespace.
• R-Administrators (system-wide [Administrator][UserRole::Administrator] users) can list all users on the system.

Errors

Returns an Error::Api if retrieving the list of all User IDs fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespce1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// add the accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
// the N-Administrator only sees itself
assert_eq!(nethsm.get_users()?.len(), 1);

// use the credentials of the R-Administrator
nethsm.use_credentials(&"admin".parse()?)?;
// the R-Administrator sees at least itself and the previously created N-Administrator
assert!(nethsm.get_users()?.len() >= 2);

pub fn get_user(&self, user_id: &UserId) -> Result<UserData, Error>

Gets information of a user.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) can only access information about users in their own namespace.
• R-Administrators (system-wide [Administrator][UserRole::Administrator] users) can access information about all users on the system.

Errors

Returns an Error::Api if retrieving information of the user fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the user identified by user_id does not exist
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role
• the used [Credentials] do not provide access to information about a user in the targeted namespace (N-Administrator of a different namespace)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;

// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespce1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// add the accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
// the N-Administrator sees itself
println!("{:?}", nethsm.get_user(&"namespace1~admin1".parse()?)?);
// the N-Administrator can not see the R-Administrator
assert!(nethsm.get_user(&"admin".parse()?).is_err());

nethsm.use_credentials(&"admin".parse()?)?;
// the R-Administrator sees itself
println!("{:?}", nethsm.get_user(&"admin".parse()?)?);
// the R-Administrator sees the N-Administrator
println!("{:?}", nethsm.get_user(&"namespace1~admin1".parse()?)?);
// this fails if the user does not exist
assert!(nethsm.get_user(&"user1".parse()?).is_err());

pub fn set_user_passphrase( &self, user_id: UserId, passphrase: Passphrase, ) -> Result<(), Error>

Sets the passphrase for a user on the NetHSM.

Namespaces

N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) are only able to set the passphrases for users in their own namespace. R-Administrators (system-wide [Administrator][UserRole::Administrator] users) are only able to set the passphrases for system-wide users.

Internally, this function also calls add_credentials to add the updated user [Credentials] to the list of available ones. If the calling user is in the [Administrator][UserRole::Administrator] role and changes their own passphrase, additionally use_credentials is called to use the updated passphrase after changing it.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Errors

Returns an Error::Api if setting the passphrase for the user fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the user identified by user_id does not exist
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role
• the targeted user is in a namespace, but the caller is not an [Administrator][UserRole::Administrator] of that namespace (N-Administrator)
• the targeted user is a system-wide user, but the caller is not a system-wide [Administrator][UserRole::Administrator] (R-Administrator)

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespce1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// add the accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;

// the R-Administrator can set its own passphrase
nethsm.set_user_passphrase(
    "admin".parse()?,
    Passphrase::new("new-admin-passphrase".to_string()),
)?;
// the R-Administrator can not set the N-Administrator's passphrase
assert!(
    nethsm
        .set_user_passphrase(
            "namespace1~admin".parse()?,
            Passphrase::new("new-admin-passphrase".to_string()),
        )
        .is_err()
);

// the N-Administrator can set its own passphrase
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
nethsm.set_user_passphrase(
    "namespace1~admin1".parse()?,
    Passphrase::new("new-admin-passphrase".to_string()),
)?;
// the N-Administrator can not set the R-Administrator's passphrase
assert!(
    nethsm
        .set_user_passphrase(
            "admin".parse()?,
            Passphrase::new("new-admin-passphrase".to_string())
        )
        .is_err()
);

pub fn add_user_tag(&self, user_id: &UserId, tag: &str) -> Result<(), Error>

Adds a tag to a user in the [Operator][UserRole::Operator] role.

A tag provides the user identified by user_id with access to keys in their namespace, that are tagged with that same tag.

NOTE: The tag for the key in the same namespace must be added beforehand, by calling add_key_tag.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) are only able to add tags for users in their own namespace.
• R-Administrators (system-wide [Administrator][UserRole::Administrator] users) are only able to add tags for system-wide users.

Errors

Returns an Error::Api if adding the tag for the user fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the user identified by user_id does not exist
• the user identified by user_id is not in the [Operator][UserRole::Operator] role
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role
• the caller does not have access to the target user’s namespace

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    Passphrase,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespce1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// add a user in the Operator role for a namespace
nethsm.add_user(
    "Namespace1 Operator".to_string(),
    UserRole::Operator,
    Passphrase::new("namespce1-operator-passphrase".to_string()),
    Some("namespace1~operator1".parse()?),
)?;
// add the accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator One".to_string(),
    UserRole::Operator,
    Passphrase::new("operator1-passphrase".to_string()),
    Some("user1".parse()?),
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;

// R-Administrators can add tags for system-wide users
nethsm.add_user_tag(&"user1".parse()?, "tag1")?;
// R-Administrators can not add tags for namespace users
assert!(
    nethsm
        .add_user_tag(&"namespace1~user1".parse()?, "tag1")
        .is_err()
);

// user tags in namespaces
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
// generate key in namespace1 with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing2".parse()?),
    Some(vec!["tag2".to_string()]),
)?;
// N-Administrators can not add tags to system-wide users
assert!(nethsm.add_user_tag(&"user1".parse()?, "tag2").is_err());
// N-Administrators can add tags to users in their own namespace
nethsm.add_user_tag(&"namespace1~user1".parse()?, "tag2")?;

pub fn delete_user_tag(&self, user_id: &UserId, tag: &str) -> Result<(), Error>

Deletes a tag from a user in the [Operator][UserRole::Operator] role.

Removes a tag from a target user identified by user_id, which removes its access to any key in their namespace, that carries the same tag.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) are only able to delete tags for users in their own namespace.
• R-Administrators (system-wide [Administrator][UserRole::Administrator] users) are only able to delete tags for system-wide users.

Errors

Returns an Error::Api if deleting the tag from the user fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the user identified by user_id does not exist
• the user identified by user_id is not in the [Operator][UserRole::Operator] role
• the tag is not added to user identified by user_id
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role
• the caller does not have access to the target user’s namespace

Examples

use nethsm::{
    Connection,
    ConnectionSecurity,
    Credentials,
    KeyMechanism,
    KeyType,
    NetHsm,
    Passphrase,
    UserRole,
};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespce1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// add a user in the Operator role for a namespace
nethsm.add_user(
    "Namespace1 Operator".to_string(),
    UserRole::Operator,
    Passphrase::new("namespce1-operator-passphrase".to_string()),
    Some("namespace1~operator1".parse()?),
)?;
// add the accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator One".to_string(),
    UserRole::Operator,
    Passphrase::new("operator1-passphrase".to_string()),
    Some("user1".parse()?),
)?;
// generate system-wide key with tag
nethsm.generate_key(
    KeyType::Curve25519,
    vec![KeyMechanism::EdDsaSignature],
    None,
    Some("signing1".parse()?),
    Some(vec!["tag1".to_string()]),
)?;
// add tag for system-wide user
nethsm.add_user_tag(&"user1".parse()?, "tag1")?;

// N-Administrators can not delete tags from system-wide Operator users
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.delete_user_tag(&"user1".parse()?, "tag2").is_err());

// R-Administrators can delete tags from system-wide Operator users
nethsm.use_credentials(&"admin".parse()?)?;
nethsm.delete_user_tag(&"user1".parse()?, "tag1")?;

pub fn get_user_tags(&self, user_id: &UserId) -> Result<Vec<String>, Error>

Gets all tags of a user in the [Operator][UserRole::Operator] role.

This call requires using [Credentials] of a user in the [Administrator][UserRole::Administrator] role.

Namespaces

• N-Administrators ([Administrator][UserRole::Administrator] users in a given namespace) are only able to get tags of users in their own namespace.
• R-Administrators (system-wide [Administrator][UserRole::Administrator] users) are able to get tags of system-wide and all namespace users.

Errors

Returns an Error::Api if getting the tags for the user fails:

• the NetHSM is not in [Operational][SystemState::Operational] state
• the user identified by user_id does not exist
• the user identified by user_id is not in the [Operator][UserRole::Operator] role
• the used [Credentials] are not correct
• the used [Credentials] are not that of a user in the [Administrator][UserRole::Administrator] role
• the caller does not have access to the target user’s namespace

Examples

use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase, UserRole};

// create a connection with a system-wide user in the Administrator role (R-Administrator)
let nethsm = NetHsm::new(
    Connection::new(
        "https://example.org/api/v1".try_into()?,
        ConnectionSecurity::Unsafe,
    ),
    Some(Credentials::new(
        "admin".parse()?,
        Some(Passphrase::new("passphrase".to_string())),
    )),
    None,
    None,
)?;
// add a user in the Administrator role for a namespace (N-Administrator)
nethsm.add_user(
    "Namespace1 Admin".to_string(),
    UserRole::Administrator,
    Passphrase::new("namespce1-admin-passphrase".to_string()),
    Some("namespace1~admin1".parse()?),
)?;
// add the accompanying namespace
nethsm.add_namespace(&"namespace1".parse()?)?;
// add a system-wide user in the Operator role
nethsm.add_user(
    "Operator One".to_string(),
    UserRole::Operator,
    Passphrase::new("operator1-passphrase".to_string()),
    Some("user1".parse()?),
)?;

// R-Administrators can access tags of all users
assert!(nethsm.get_user_tags(&"user1".parse()?)?.is_empty());
// add a tag for the user
nethsm.add_user_tag(&"user1".parse()?, "tag1")?;
assert_eq!(nethsm.get_user_tags(&"user1".parse()?)?.len(), 1);

// N-Administrators can not access tags of system-wide users
nethsm.use_credentials(&"namespace1~admin1".parse()?)?;
assert!(nethsm.get_user_tags(&"user1".parse()?).is_err());

Trait Implementations

impl Debug for NetHsm

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

Formats the value using the given formatter.