// SPDX-FileCopyrightText: 2024 David Runge <dvzrv@archlinux.org>
// SPDX-License-Identifier: Apache-2.0 OR MIT

//! A high-level library to interact with the API of a [Nitrokey NetHSM](https://docs.nitrokey.com/nethsm/)
//!
//! Provides high-level integration with a Nitrokey NetHSM and official container.
//! As this crate is a wrapper around [`nethsm_sdk_rs`] it covers all available actions from
//! provisioning, over key and user management to backup and restore.
//!
//! The NetHSM provides dedicated [user management](https://docs.nitrokey.com/nethsm/administration#user-management)
//! based on several roles (see [`UserRole`]) which can be used to separate concerns.
//!
//! The cryptographic key material on the device can be assigned to one or several [tags](https://docs.nitrokey.com/nethsm/operation#tags-for-keys).
//! Users in the "operator" role can be assigned to the same [tags](https://docs.nitrokey.com/nethsm/administration#tags-for-users)
//! to gain access to the keys.
//!
//! Apart from the crate specific documentation it is very recommended to read the canonical
//! upstream documentation as well: <https://docs.nitrokey.com/nethsm/>
//!
//! This crate re-exports the following [`nethsm_sdk_rs`] types so that the crate does not have to
//! be relied on directly:
//! * [`nethsm_sdk_rs::models::DecryptMode`]
//! * [`nethsm_sdk_rs::models::DistinguishedName`]
//! * [`nethsm_sdk_rs::models::EncryptMode`]
//! * [`nethsm_sdk_rs::models::KeyMechanism`]
//! * [`nethsm_sdk_rs::models::KeyType`]
//! * [`nethsm_sdk_rs::models::LogLevel`]
//! * [`nethsm_sdk_rs::models::NetworkConfig`]
//! * [`nethsm_sdk_rs::models::SystemState`]
//! * [`nethsm_sdk_rs::models::TlsKeyType`]
//! * [`nethsm_sdk_rs::models::UserRole`]
//!
//! Using the [`NetHsm`] struct it is possible to establish a TLS connection for multiple users.
//! TLS validation can be configured based on a variant of the [`ConnectionSecurity`] enum:
//! - [`ConnectionSecurity::Unsafe`]: The host certificate is not validated.
//! - [`ConnectionSecurity::Fingerprints`]: The host certificate is validated based on configurable
//!   fingerprints.
//! - [`ConnectionSecurity::Native`]: The host certificate is validated using the native Operating
//!   System trust store.
//!
//! # Examples
//!
//! ```
//! use nethsm::{ConnectionSecurity, Error, NetHsm};
//!
//! # fn main() -> Result<(), Error> {
//! // Create a new connection to a NetHSM at "https://example.org" using admin credentials
//! let nethsm = NetHsm::new(
//!     "https://example.org/api/v1".to_string(),
//!     ConnectionSecurity::Unsafe,
//!     Some(("admin".to_string(), Some("passphrase".to_string()))),
//!     None,
//!     None,
//! )?;
//!
//! // Connections can be initialized without any credentials and more than one can be provided later on
//! let nethsm = NetHsm::new(
//!     "https://example.org/api/v1".to_string(),
//!     ConnectionSecurity::Unsafe,
//!     None,
//!     None,
//!     None,
//! )?;
//!
//! nethsm.add_credentials(("admin".to_string(), Some("passphrase".to_string())));
//! nethsm.add_credentials(("user1".to_string(), Some("other_passphrase".to_string())));
//!
//! // A set of credentials must be used before establishing a connection with the configured NetHSM
//! nethsm.use_credentials("user1")?;
//! # Ok(())
//! # }
//! ```
use std::cell::RefCell;
use std::net::Ipv4Addr;
use std::sync::Arc;
use std::thread::available_parallelism;
use std::time::Duration;

use base64ct::{Base64, Encoding};
use chrono::{DateTime, Utc};
use log::{debug, error, info};
use md5::Md5;
use nethsm_sdk_rs::apis::configuration::{BasicAuth, Configuration};
use nethsm_sdk_rs::apis::default_api::{
    config_backup_passphrase_put,
    config_logging_get,
    config_logging_put,
    config_network_get,
    config_network_put,
    config_time_get,
    config_time_put,
    config_tls_cert_pem_get,
    config_tls_cert_pem_put,
    config_tls_csr_pem_post,
    config_tls_generate_post,
    config_unattended_boot_get,
    config_unattended_boot_put,
    config_unlock_passphrase_put,
    health_state_get,
    info_get,
    keys_generate_post,
    keys_get,
    keys_key_id_cert_delete,
    keys_key_id_cert_get,
    keys_key_id_cert_put,
    keys_key_id_csr_pem_post,
    keys_key_id_decrypt_post,
    keys_key_id_delete,
    keys_key_id_encrypt_post,
    keys_key_id_get,
    keys_key_id_public_pem_get,
    keys_key_id_put,
    keys_key_id_restrictions_tags_tag_delete,
    keys_key_id_restrictions_tags_tag_put,
    keys_key_id_sign_post,
    keys_post,
    lock_post,
    metrics_get,
    provision_post,
    random_post,
    system_backup_post,
    system_cancel_update_post,
    system_commit_update_post,
    system_factory_reset_post,
    system_reboot_post,
    system_restore_post,
    system_shutdown_post,
    system_update_post,
    unlock_post,
    users_get,
    users_post,
    users_user_id_delete,
    users_user_id_get,
    users_user_id_passphrase_post,
    users_user_id_put,
    users_user_id_tags_get,
    users_user_id_tags_tag_delete,
    users_user_id_tags_tag_put,
    KeysPostBody,
};
use nethsm_sdk_rs::models::{
    BackupPassphraseConfig,
    DecryptRequestData,
    EncryptRequestData,
    InfoData,
    KeyGenerateRequestData,
    KeyRestrictions,
    LoggingConfig,
    PrivateKey,
    ProvisionRequestData,
    PublicKey,
    RandomRequestData,
    SignRequestData,
    SystemUpdateData,
    TimeConfig,
    TlsKeyGenerateRequestData,
    UnlockPassphraseConfig,
    UnlockRequestData,
    UserData,
    UserPassphrasePostData,
    UserPostData,
};
// Re-export some useful types so that users do not have to use nethsm-sdk-rs directly
pub use nethsm_sdk_rs::models::{
    DecryptMode,
    DistinguishedName,
    EncryptMode,
    KeyMechanism,
    KeyType,
    LogLevel,
    NetworkConfig,
    SystemState,
    TlsKeyType,
    UserRole,
};
use nethsm_sdk_rs::ureq::AgentBuilder;
use rustls::crypto::{aws_lc_rs as tls_provider, CryptoProvider};
use rustls::ClientConfig;
use serde_json::Value;
use sha1::Sha1;
use sha2::{Digest, Sha224, Sha256, Sha384, Sha512};

mod nethsm_sdk;
use nethsm_sdk::{match_key_type_and_mechanisms, NetHsmApiError};
pub use nethsm_sdk::{BootMode, KeyImportData, SignatureType};
mod tls;
pub use tls::{ConnectionSecurity, HostCertificateFingerprints};
use tls::{DangerIgnoreVerifier, FingerprintVerifier};

const USER_AGENT: &str = "signstar-nethsm/0.1.0";

#[derive(Debug, thiserror::Error)]
pub enum Error {
    /// Wraps a [`rustls::Error`] for issues with rustls based TLS setups
    #[error("TLS error: {0}")]
    Rustls(#[from] rustls::Error),

    /// A Base64 encoded string can not be decode
    #[error("Decoding Base64 string failed: {0}")]
    Base64Decode(base64ct::Error),

    /// A generic error with a custom message
    #[error("NetHSM error: {0}")]
    Default(String),

    /// The loading of TLS root certificates from the platform's native certificate store failed
    #[error("Loading system TLS certs failed")]
    CertLoading,

    /// A call to the NetHSM API failed
    #[error("NetHSM API error: {0}")]
    Api(String),

    /// Provided key data is invalid
    #[error("Key data invalid: {0}")]
    KeyData(String),

    /// Importing a key failed because of insufficient or malformed data
    #[error("Key import failed: {0}")]
    KeyImport(String),
}

/// 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.
pub struct NetHsm {
    /// The API configuration for a NetHSM
    config: RefCell<Configuration>,
    /// Credentials for interacting with the NetHSM using [`NetHsm::config`]
    users: RefCell<Vec<BasicAuth>>,
}

impl NetHsm {
    /// Creates a new NetHSM connection
    ///
    /// Creates a new NetHSM connection based on the `url` of the API and a chosen
    /// `connection_security` for TLS (see [`ConnectionSecurity`]).
    ///
    /// 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
    ///
    /// Returns an [`Error`] if the rustls based [`ClientConfig`] can not be created.
    pub fn new(
        url: String,
        connection_security: ConnectionSecurity,
        credentials: Option<BasicAuth>,
        max_idle_connections: Option<usize>,
        timeout_seconds: Option<u64>,
    ) -> Result<Self, Error> {
        let tls_conf = {
            let tls_conf = ClientConfig::builder_with_provider(Arc::new(CryptoProvider {
                cipher_suites: tls_provider::ALL_CIPHER_SUITES.into(),
                ..tls_provider::default_provider()
            }))
            .with_protocol_versions(rustls::DEFAULT_VERSIONS)?;

            match connection_security {
                ConnectionSecurity::Unsafe => {
                    let dangerous = tls_conf.dangerous();
                    dangerous
                        .with_custom_certificate_verifier(Arc::new(DangerIgnoreVerifier(
                            tls_provider::default_provider(),
                        )))
                        .with_no_client_auth()
                }
                ConnectionSecurity::Native => {
                    let mut roots = rustls::RootCertStore::empty();
                    let native_certs = rustls_native_certs::load_native_certs().map_err(|err| {
                        error!("Failed to load certificates: {err}");
                        Error::CertLoading
                    })?;

                    let (added, failed) = roots.add_parsable_certificates(native_certs);
                    debug!("Added {added} certificates and failed to parse {failed} certificates");

                    if added == 0 {
                        error!("Added no native certificates");
                        return Err(Error::CertLoading);
                    }

                    tls_conf.with_root_certificates(roots).with_no_client_auth()
                }
                ConnectionSecurity::Fingerprints(fingerprints) => {
                    let dangerous = tls_conf.dangerous();
                    dangerous
                        .with_custom_certificate_verifier(Arc::new(FingerprintVerifier {
                            fingerprints,
                            provider: tls_provider::default_provider(),
                        }))
                        .with_no_client_auth()
                }
            }
        };

        let agent = {
            let max_idle_connections = max_idle_connections
                .or_else(|| available_parallelism().ok().map(Into::into))
                .unwrap_or(100);
            let timeout_seconds = timeout_seconds.unwrap_or(10);
            info!(
                "NetHSM connection configured with \"max_idle_connection\" {} and \"timeout_seconds\" {}.",
                max_idle_connections, timeout_seconds
            );

            AgentBuilder::new()
                .tls_config(Arc::new(tls_conf))
                .max_idle_connections(max_idle_connections)
                .max_idle_connections_per_host(max_idle_connections)
                .timeout_connect(Duration::from_secs(timeout_seconds))
                .build()
        };

        let api_config = RefCell::new(Configuration {
            client: agent,
            base_path: url,
            basic_auth: credentials.clone(),
            user_agent: Some(USER_AGENT.to_string()),
            ..Default::default()
        });

        let users = {
            let mut users = vec![];
            if let Some(credentials) = credentials {
                users.push(credentials)
            }
            RefCell::new(users)
        };

        Ok(Self {
            config: api_config,
            users,
        })
    }

    /// Sets the URL for the NetHSM connection
    ///
    /// # Examples
    ///
    /// ```
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // Create a new connection for a NetHSM at "https://example.org"
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     None,
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // change the url to something else
    /// nethsm.set_url("https://other.org/api/v1".to_string());
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_url(&self, url: String) {
        self.config.borrow_mut().base_path = url;
    }

    /// Adds credentials to the list of available credentials
    ///
    /// # Examples
    ///
    /// ```
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     None,
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // add credentials
    /// nethsm.add_credentials(("admin".to_string(), Some("passphrase".to_string())));
    /// nethsm.add_credentials(("user1".to_string(), Some("other_passphrase".to_string())));
    /// nethsm.add_credentials(("user2".to_string(), None));
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_credentials(&self, credentials: BasicAuth) {
        // remove any previously existing credentials (User IDs are unique)
        self.remove_credentials(&credentials.0);
        self.users.borrow_mut().push(credentials)
    }

    /// Removes credentials from the list of available and currently used ones
    ///
    /// Removes credentials from the list of available credentials and if identical unsets the
    /// credentials for current authentication as well.
    ///
    /// # Examples
    ///
    /// ```
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // remove credentials
    /// nethsm.remove_credentials("admin");
    /// # Ok(())
    /// # }
    /// ```
    pub fn remove_credentials(&self, user_id: &str) {
        self.users.borrow_mut().retain(|cred| cred.0 != user_id);
        if self
            .config
            .borrow()
            .basic_auth
            .as_ref()
            .is_some_and(|x| x.0 == user_id)
        {
            self.config.borrow_mut().basic_auth = None;
        }
    }

    /// Sets credentials to use for the next connection
    ///
    /// # Errors
    ///
    /// An [`Error`] is returned if no credentials with the User ID `user_id` can be found.
    ///
    /// # Examples
    ///
    /// ```
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     None,
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // add credentials
    /// nethsm.add_credentials(("admin".to_string(), Some("passphrase".to_string())));
    /// nethsm.add_credentials(("user1".to_string(), Some("other_passphrase".to_string())));
    ///
    /// // use admin credentials
    /// nethsm.use_credentials("admin")?;
    ///
    /// // use operator credentials
    /// nethsm.use_credentials("user1")?;
    ///
    /// // this fails, because the user has not been added yet
    /// assert!(nethsm.use_credentials("user2").is_err());
    /// # Ok(())
    /// # }
    /// ```
    pub fn use_credentials(&self, user_id: &str) -> Result<(), Error> {
        if let Some(basic_auth) = self
            .users
            .borrow()
            .iter()
            .find(|&basic_auth| basic_auth.0 == user_id)
        {
            let passphrase = basic_auth.1.as_ref().cloned();
            self.config.borrow_mut().basic_auth = Some((basic_auth.0.clone(), passphrase));
            Ok(())
        } else {
            Err(Error::Default(format!(
                "The credentials for User ID \"{}\" needs to be added before it can be used!",
                user_id
            )))
        }
    }

    /// Provisions a NetHSM
    ///
    /// [Provisioning](https://docs.nitrokey.com/nethsm/getting-started#provisioning) is the initial setup step for a device.
    /// It sets the `unlock_passphrase` which is used for unlocking a device that is using attended
    /// boot (see [`BootMode::Attended`]), the initial `admin_passphrase` for the default
    /// administrator account ("admin") and the `system_time`.
    /// The unlock passphrase can later on be changed using [`NetHsm::set_unlock_passphrase`] and
    /// the admin passphrase using [`NetHsm::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 device is not in state [`SystemState::Unprovisioned`]
    /// * the provided data is malformed
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use chrono::Utc;
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // no initial credentials are required
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     None,
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // provision the device
    /// nethsm.provision(
    ///     "unlock-the-device".to_string(),
    ///     "admin-passphrase".to_string(),
    ///     Utc::now(),
    /// )?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn provision(
        &self,
        unlock_passphrase: String,
        admin_passphrase: String,
        system_time: DateTime<Utc>,
    ) -> Result<(), Error> {
        let provision_request_data = ProvisionRequestData::new(
            unlock_passphrase,
            admin_passphrase,
            system_time.to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
        );
        provision_post(&self.config.borrow(), provision_request_data).map_err(|error| {
            Error::Api(format!(
                "Provisioning failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Returns the system state of the NetHSM instance
    ///
    /// Returns a variant of [`SystemState`], which describes the [state](https://docs.nitrokey.com/nethsm/administration#state) a device 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
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // no initial credentials are required
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     None,
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // retrieve the state
    /// println!("{:?}", nethsm.state()?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn state(&self) -> Result<SystemState, Error> {
        let health_state = health_state_get(&self.config.borrow()).map_err(|error| {
            Error::Api(format!(
                "Retrieving state failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(health_state.entity.state)
    }

    /// Returns device information for the NetHSM instance
    ///
    /// Returns an [`InfoData`], which provides the [device information](https://docs.nitrokey.com/nethsm/administration#device-information).
    ///
    /// For this call no credentials are required and if any are configured, they are ignored.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if the device information can not be retrieved.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // no initial credentials are required
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     None,
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // retrieve the device info
    /// println!("{:?}", nethsm.info()?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn info(&self) -> Result<InfoData, Error> {
        let info = info_get(&self.config.borrow()).map_err(|error| {
            Error::Api(format!(
                "Retrieving device information failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(info.entity)
    }

    /// Returns metrics for the NetHSM instance
    ///
    /// Returns a [`serde_json::Value`] which provides [metrics](https://docs.nitrokey.com/nethsm/administration#metrics) for the device.
    ///
    /// This call requires using credentials of a user in the "metrics" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if the device metrics can not be retrieved:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "metrics" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "metrics" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some((
    ///         "metrics".to_string(),
    ///         Some("metrics-passphrase".to_string()),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // retrieve the metrics
    /// println!("{:?}", nethsm.metrics()?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn metrics(&self) -> Result<Value, Error> {
        let metrics = metrics_get(&self.config.borrow()).map_err(|error| {
            Error::Api(format!(
                "Retrieving metrics failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(metrics.entity)
    }

    /// Sets the unlock passphrase for the NetHSM instance
    ///
    /// Sets `current_passphrase` to `new_passphrase`, which changes the [unlock passphrase](https://docs.nitrokey.com/nethsm/administration#unlock-passphrase) for the device.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if the unlock passphrase can not be changed:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the provided `current_passphrase` is not correct
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // set the unlock passphrase
    /// nethsm.set_unlock_passphrase(
    ///     "current-unlock-passphrase".to_string(),
    ///     "new-unlock-passphrase".to_string(),
    /// )?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_unlock_passphrase(
        &self,
        current_passphrase: String,
        new_passphrase: String,
    ) -> Result<(), Error> {
        config_unlock_passphrase_put(
            &self.config.borrow(),
            UnlockPassphraseConfig::new(new_passphrase, current_passphrase),
        )
        .map_err(|error| {
            Error::Api(format!(
                "Changing unlock passphrase failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Returns the boot mode
    ///
    /// Returns a variant of [`BootMode`] which represents the device's [boot mode](https://docs.nitrokey.com/nethsm/administration#boot-mode).
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if the boot mode can not be retrieved:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // retrieve the boot mode
    /// println!("{:?}", nethsm.get_boot_mode()?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_boot_mode(&self) -> Result<BootMode, Error> {
        Ok(BootMode::from(
            config_unattended_boot_get(&self.config.borrow())
                .map_err(|error| {
                    Error::Api(format!(
                        "Retrieving boot mode failed: {}",
                        NetHsmApiError::from(error)
                    ))
                })?
                .entity,
        ))
    }

    /// Sets the boot mode
    ///
    /// Sets the device's [boot mode](https://docs.nitrokey.com/nethsm/administration#boot-mode) based on a [`BootMode`] variant.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if the boot mode can not be set:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{BootMode, ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // set the boot mode to unattended
    /// nethsm.set_boot_mode(BootMode::Unattended)?;
    ///
    /// // set the boot mode to attended
    /// nethsm.set_boot_mode(BootMode::Attended)?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_boot_mode(&self, boot_mode: BootMode) -> Result<(), Error> {
        config_unattended_boot_put(&self.config.borrow(), boot_mode.into()).map_err(|error| {
            Error::Api(format!(
                "Setting boot mode failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Returns the TLS certificate of the API
    ///
    /// Returns the device's [TLS certificate](https://docs.nitrokey.com/nethsm/administration#tls-certificate) which is used for communication with the API.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if the device's TLS certificate can not be retrieved:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get the TLS certificate
    /// println!("{}", nethsm.get_tls_cert()?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_tls_cert(&self) -> Result<String, Error> {
        Ok(config_tls_cert_pem_get(&self.config.borrow())
            .map_err(|error| {
                Error::Api(format!(
                    "Retrieving API TLS certificate failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity)
    }

    /// Returns a Certificate Signing Request (CSR) for the API's TLS certificate
    ///
    /// Based on data from an instance of [`nethsm_sdk_rs::models::DistinguishedName`] returns a
    /// [Certificate Signing Request (CSR)](https://en.wikipedia.org/wiki/Certificate_signing_request)
    /// in [PKCS#10](https://en.wikipedia.org/wiki/Certificate_signing_request#Structure_of_a_PKCS_#10_CSR) format
    /// for the device's [TLS certificate](https://docs.nitrokey.com/nethsm/administration#tls-certificate)
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if the CSR can not be retrieved:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, DistinguishedName, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get the CSR for 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()),
    ///     })?
    /// );
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_tls_csr(&self, distinguished_name: DistinguishedName) -> Result<String, Error> {
        Ok(
            config_tls_csr_pem_post(&self.config.borrow(), distinguished_name)
                .map_err(|error| {
                    Error::Api(format!(
                        "Retrieving CSR for TLS certificate failed: {}",
                        NetHsmApiError::from(error),
                    ))
                })?
                .entity,
        )
    }

    /// Generates a new TLS certificate for the API
    ///
    /// Based on `tls_key_type` and `length` generates a new
    /// [TLS certificate](https://docs.nitrokey.com/nethsm/administration#tls-certificate)
    /// (used for communication with the API).
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if the new TLS certificate can not be generated:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the `tls_key_type` and `length` combination is not valid
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, TlsKeyType};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // generate a new TLS certificate
    /// nethsm.generate_tls_cert(TlsKeyType::Rsa, Some(4096))?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn generate_tls_cert(
        &self,
        tls_key_type: TlsKeyType,
        length: Option<i32>,
    ) -> Result<(), Error> {
        config_tls_generate_post(
            &self.config.borrow(),
            TlsKeyGenerateRequestData {
                r#type: tls_key_type,
                length,
            },
        )
        .map_err(|error| {
            Error::Api(format!(
                "Generating API TLS certificate failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Sets a new TLS certificate for the API
    ///
    /// Accepts a Base64 encoded [DER](https://en.wikipedia.org/wiki/X.690#DER_encoding) certificate via `certificate`
    /// which is added as new [TLS certificate](https://docs.nitrokey.com/nethsm/administration#tls-certificate) for
    /// communication with the API.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if setting a new TLS certificate fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the provided `certificate` is not valid
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// let cert = r#"-----BEGIN CERTIFICATE-----
    /// MIIBHjCBxKADAgECAghDngCv6xWIXDAKBggqhkjOPQQDAjAUMRIwEAYDVQQDDAlr
    /// ZXlmZW5kZXIwIBcNNzAwMTAxMDAwMDAwWhgPOTk5OTEyMzEyMzU5NTlaMBQxEjAQ
    /// BgNVBAMMCWtleWZlbmRlcjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABJsHIrsZ
    /// 6fJzrk12GK7nW6bGyTIIZiQUq0uaKbn21dgPiDCO5+iYVXAqnWu4IMVZQnkFJmte
    /// PRUUuM3119f8ffkwCgYIKoZIzj0EAwIDSQAwRgIhALH4fDYJ21tRecXp9IipBlil
    /// p+hJCj77zBvFmGYy/UnPAiEA8csj7U6BfzvK4EiQyUZa7/as+nXwj3XHU/i8LyLm
    /// Chw=
    /// -----END CERTIFICATE-----"#;
    ///
    /// // set a new TLS certificate
    /// nethsm.set_tls_cert(cert)?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_tls_cert(&self, certificate: &str) -> Result<(), Error> {
        config_tls_cert_pem_put(&self.config.borrow(), certificate).map_err(|error| {
            Error::Api(format!(
                "Setting API TLS certificate failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Gets the network configuration
    ///
    /// Retrieves the [network configuration](https://docs.nitrokey.com/nethsm/administration#network) of the device in
    /// the form of a [`nethsm_sdk_rs::models::NetworkConfig`].
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if retrieving network configuration fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get the network configuration
    /// println!("{:?}", nethsm.get_network()?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_network(&self) -> Result<NetworkConfig, Error> {
        Ok(config_network_get(&self.config.borrow())
            .map_err(|error| {
                Error::Api(format!(
                    "Getting network config failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity)
    }

    /// Sets the network configuration
    ///
    /// Sets the [network configuration](https://docs.nitrokey.com/nethsm/administration#network) of the device based on
    /// a [`nethsm_sdk_rs::models::NetworkConfig`].
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if setting the network configuration fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the provided `network_config` is not valid
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, NetworkConfig};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// let network_config = NetworkConfig::new(
    ///     "192.168.1.1".to_string(),
    ///     "255.255.255.0".to_string(),
    ///     "0.0.0.0".to_string(),
    /// );
    ///
    /// // set the network configuration
    /// nethsm.set_network(network_config)?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_network(&self, network_config: NetworkConfig) -> Result<(), Error> {
        config_network_put(&self.config.borrow(), network_config).map_err(|error| {
            Error::Api(format!(
                "Setting network config failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Gets the device's time
    ///
    /// Retrieves the current [time](https://docs.nitrokey.com/nethsm/administration#time) of the device.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if retrieving time fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get the time
    /// println!("{:?}", nethsm.get_time()?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_time(&self) -> Result<String, Error> {
        Ok(config_time_get(&self.config.borrow())
            .map_err(|error| {
                Error::Api(format!(
                    "Getting device time failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity
            .time)
    }

    /// Sets the device's time
    ///
    /// Sets the [time](https://docs.nitrokey.com/nethsm/administration#time) for the device.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if setting time fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the provided `time` is not valid
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use chrono::Utc;
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// let time = Utc::now();
    /// // set the time
    /// nethsm.set_time(time)?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_time(&self, time: DateTime<Utc>) -> Result<(), Error> {
        config_time_put(
            &self.config.borrow(),
            TimeConfig::new(time.to_rfc3339_opts(chrono::SecondsFormat::Secs, true)),
        )
        .map_err(|error| {
            Error::Api(format!(
                "Setting device time failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Gets the logging configuration
    ///
    /// Retrieves the current [logging configuration](https://docs.nitrokey.com/nethsm/administration#logging) of the device.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if getting logging configuration fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get logging configuration
    /// println!("{:?}", nethsm.get_logging()?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_logging(&self) -> Result<LoggingConfig, Error> {
        Ok(config_logging_get(&self.config.borrow())
            .map_err(|error| {
                Error::Api(format!(
                    "Getting logging config failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity)
    }

    /// Sets the logging configuration
    ///
    /// Sets the device's [logging configuration](https://docs.nitrokey.com/nethsm/administration#logging).
    /// A host to send logs to is defined with `ip_address` and `port`. The log level is configured
    /// using `log_level`.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if setting the logging configuration fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * 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 user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::net::Ipv4Addr;
    ///
    /// use nethsm::{ConnectionSecurity, Error, LogLevel, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // set logging configuration
    /// println!(
    ///     "{:?}",
    ///     nethsm.set_logging(Ipv4Addr::new(192, 168, 1, 2), 513, LogLevel::Debug)?
    /// );
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_logging(
        &self,
        ip_address: Ipv4Addr,
        port: i32,
        log_level: LogLevel,
    ) -> Result<(), Error> {
        let ip_address = ip_address.to_string();
        config_logging_put(
            &self.config.borrow(),
            LoggingConfig::new(ip_address, port, log_level),
        )
        .map_err(|error| {
            Error::Api(format!(
                "Setting logging config failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Sets the backup passphrase
    ///
    /// Sets `current_passphrase` to `new_passphrase`, which changes the [backup](https://docs.nitrokey.com/nethsm/administration#backup) passphrase for the device.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if setting the backup passphrase fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the provided `current_passphrase` is not correct
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // set the backup passphrase
    /// nethsm.set_backup_passphrase(
    ///     "current-backup-passphrase".to_string(),
    ///     "new-backup-passphrase".to_string(),
    /// )?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_backup_passphrase(
        &self,
        current_passphrase: String,
        new_passphrase: String,
    ) -> Result<(), Error> {
        config_backup_passphrase_put(
            &self.config.borrow(),
            BackupPassphraseConfig::new(new_passphrase, current_passphrase),
        )
        .map_err(|error| {
            Error::Api(format!(
                "Setting backup passphrase failed: {}",
                NetHsmApiError::from(error),
            ))
        })?;
        Ok(())
    }

    /// Creates a backup
    ///
    /// Triggers the creation and download of a [backup](https://docs.nitrokey.com/nethsm/administration#backup) of the device.
    /// Before creating a backup, [`NetHsm::set_backup_passphrase`] has to be called once to set a
    /// passphrase for the backup.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if creating a backup fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::path::PathBuf;
    ///
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // create a backup and write it to file
    /// let backup_file = PathBuf::from("nethsm.bkp");
    /// std::fs::write(backup_file, nethsm.backup()?).unwrap();
    /// # Ok(())
    /// # }
    /// ```
    pub fn backup(&self) -> Result<Vec<u8>, Error> {
        Ok(system_backup_post(&self.config.borrow())
            .map_err(|error| {
                Error::Api(format!(
                    "Getting backup failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity)
    }

    /// Triggers a factory reset
    ///
    /// Triggers a [factory reset](https://docs.nitrokey.com/nethsm/administration#reset-to-factory-defaults) for the device.
    /// This action deletes all user and system data! Make sure to create a backup using
    /// [`NetHsm::backup`] first!
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if resetting the device fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, SystemState};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// assert_eq!(nethsm.state()?, SystemState::Operational);
    /// // trigger a factory reset
    /// nethsm.factory_reset()?;
    /// assert_eq!(nethsm.state()?, SystemState::Unprovisioned);
    /// # Ok(())
    /// # }
    /// ```
    pub fn factory_reset(&self) -> Result<(), Error> {
        system_factory_reset_post(&self.config.borrow()).map_err(|error| {
            Error::Api(format!(
                "Factory reset failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Restores device from backup
    ///
    /// WARNING: This function has known issues and may in fact not work! <https://github.com/Nitrokey/nethsm/issues/5>
    ///
    /// [Restores](https://docs.nitrokey.com/nethsm/administration#restore) a device from a
    /// [backup](https://docs.nitrokey.com/nethsm/administration#backup), by providing a
    /// `backup_passphrase` (set using [`NetHsm::set_backup_passphrase`]) a new `system_time` for
    /// the device and a backup (created using [`NetHsm::backup`]).
    /// The device may be in state [`SystemState::Operational`] or [`SystemState::Unprovisioned`].
    /// Any existing user data is safely removed and replaced by that of the backup. If the
    /// device is in state [`SystemState::Unprovisioned`] the system configuration from the
    /// backup is also used and the device is rebooted.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if restoring the device from backup fails:
    /// * the device is not in state [`SystemState::Operational`] or [`SystemState::Unprovisioned`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::path::PathBuf;
    ///
    /// use chrono::Utc;
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, SystemState};
    ///
    /// #
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // restore from backup
    /// let backup_file = PathBuf::from("nethsm.bkp");
    /// let backup = std::fs::read(backup_file).unwrap();
    /// nethsm.restore("backup-passphrase".to_string(), Utc::now(), backup)?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn restore(
        &self,
        backup_passphrase: String,
        system_time: DateTime<Utc>,
        backup: Vec<u8>,
    ) -> Result<(), Error> {
        system_restore_post(
            &self.config.borrow(),
            Some(nethsm_sdk_rs::models::RestoreRequestArguments {
                backup_passphrase: Some(backup_passphrase),
                system_time: Some(system_time.to_rfc3339_opts(chrono::SecondsFormat::Secs, true)),
            }),
            Some(backup),
        )
        .map_err(|error| {
            Error::Api(format!(
                "Restoring backup failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Locks the device
    ///
    /// Locks the device and sets its [state](https://docs.nitrokey.com/nethsm/administration#state) to [`SystemState::Locked`].
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if locking the device fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, SystemState};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// assert_eq!(nethsm.state()?, SystemState::Operational);
    /// // lock the device
    /// nethsm.lock()?;
    /// assert_eq!(nethsm.state()?, SystemState::Locked);
    /// # Ok(())
    /// # }
    /// ```
    pub fn lock(&self) -> Result<(), Error> {
        lock_post(&self.config.borrow()).map_err(|error| {
            Error::Api(format!(
                "Locking device failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Unlocks the device
    ///
    /// If the device is in state [`SystemState::Locked`] unlocks the device using
    /// `unlock_passphrase` and sets its [state](https://docs.nitrokey.com/nethsm/administration#state) to [`SystemState::Operational`].
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if unlocking the device fails:
    /// * the device is not in state [`SystemState::Locked`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, SystemState};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// assert_eq!(nethsm.state()?, SystemState::Locked);
    /// // unlock the device
    /// nethsm.unlock("unlock-passphrase".to_string())?;
    /// assert_eq!(nethsm.state()?, SystemState::Operational);
    /// # Ok(())
    /// # }
    /// ```
    pub fn unlock(&self, unlock_passphrase: String) -> Result<(), Error> {
        unlock_post(
            &self.config.borrow(),
            UnlockRequestData::new(unlock_passphrase),
        )
        .map_err(|error| {
            Error::Api(format!(
                "Unlocking device failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Reboots the device
    ///
    /// [Reboots](https://docs.nitrokey.com/nethsm/administration#reboot-and-shutdown) the device,
    /// if it is in state [`SystemState::Operational`].
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if rebooting the device fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, SystemState};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// assert_eq!(nethsm.state()?, SystemState::Operational);
    /// // reboot the device
    /// nethsm.reboot()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn reboot(&self) -> Result<(), Error> {
        system_reboot_post(&self.config.borrow()).map_err(|error| {
            Error::Api(format!(
                "Rebooting device failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Shuts down the device
    ///
    /// [Shuts down](https://docs.nitrokey.com/nethsm/administration#reboot-and-shutdown) the device,
    /// if it is in state [`SystemState::Operational`].
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if shutting down the device fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, SystemState};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// assert_eq!(nethsm.state()?, SystemState::Operational);
    /// // shut down the device
    /// nethsm.shutdown()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn shutdown(&self) -> Result<(), Error> {
        system_shutdown_post(&self.config.borrow()).map_err(|error| {
            Error::Api(format!(
                "Shutting down device failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// 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](https://docs.nitrokey.com/nethsm/administration#software-update) to the device,
    /// if it is in state [`SystemState::Operational`] and returns information about the software
    /// update ([`nethsm_sdk_rs::models::SystemUpdateData`]).
    /// Software updates can successively be installed ([`NetHsm::commit_update`]) or canceled
    /// ([`NetHsm::cancel_update`]).
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if uploading the software update fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, SystemState};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// let update_file = std::path::PathBuf::from("update.bin");
    /// let update = std::fs::read(update_file).unwrap();
    ///
    /// assert_eq!(nethsm.state()?, SystemState::Operational);
    /// // upload software update to device
    /// println!("{:?}", nethsm.upload_update(update)?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn upload_update(&self, update: Vec<u8>) -> Result<SystemUpdateData, Error> {
        Ok(system_update_post(&self.config.borrow(), update)
            .map_err(|error| {
                println!("error during upload");
                Error::Api(format!(
                    "Uploading update failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity)
    }

    /// Commits an uploaded software update
    ///
    /// Commits a [software update](https://docs.nitrokey.com/nethsm/administration#software-update)
    /// previously uploaded to the device (e.g. using [`NetHsm::upload_update`]), if the device is
    /// in state [`SystemState::Operational`].
    /// Successfully committing a software update leads to the reboot of the device.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if committing the software update fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * there is no software update to commit
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, SystemState};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// let update_file = std::path::PathBuf::from("update.bin");
    /// let update = std::fs::read(update_file).unwrap();
    ///
    /// assert_eq!(nethsm.state()?, SystemState::Operational);
    /// // upload software update to device
    /// println!("{:?}", nethsm.upload_update(update)?);
    /// // commit software update
    /// nethsm.commit_update()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn commit_update(&self) -> Result<(), Error> {
        system_commit_update_post(&self.config.borrow()).map_err(|error| {
            Error::Api(format!(
                "Committing update failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Cancels an uploaded software update
    ///
    /// Cancels a [software update](https://docs.nitrokey.com/nethsm/administration#software-update)
    /// previously uploaded to the device (e.g. using [`NetHsm::upload_update`]), if the device is
    /// in state [`SystemState::Operational`].
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if canceling the software update fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * there is no software update to cancel
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, SystemState};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// let update_file = std::path::PathBuf::from("update.bin");
    /// let update = std::fs::read(update_file).unwrap();
    ///
    /// assert_eq!(nethsm.state()?, SystemState::Operational);
    /// // upload software update to device
    /// println!("{:?}", nethsm.upload_update(update)?);
    /// // cancel software update
    /// nethsm.cancel_update()?;
    /// assert_eq!(nethsm.state()?, SystemState::Operational);
    /// # Ok(())
    /// # }
    /// ```
    pub fn cancel_update(&self) -> Result<(), Error> {
        system_cancel_update_post(&self.config.borrow()).map_err(|error| {
            Error::Api(format!(
                "Cancelling update failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Adds a new user on the device
    ///
    /// [Adds a user](https://docs.nitrokey.com/nethsm/administration#add-user)
    /// on the device, if the device is in state [`SystemState::Operational`] and returns the User
    /// ID of the created user.
    /// 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 device (see [`UserRole`]) and a `passphrase`.
    ///
    /// Internally, this function also calls [`NetHsm::add_credentials`] to add the new user to the
    /// list of available credentials.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if adding the user fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the provided `real_name`, `passphrase` or `user_id` are not valid
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, UserRole};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // add a user in the operator role
    /// assert_eq!(
    ///     "user1",
    ///     nethsm.add_user(
    ///         "Operator One".to_string(),
    ///         UserRole::Operator,
    ///         "operator1-passphrase".to_string(),
    ///         Some("user1".to_string()),
    ///     )?
    /// );
    ///
    /// // this fails because the user exists already
    /// assert!(nethsm
    ///     .add_user(
    ///         "Operator One".to_string(),
    ///         UserRole::Operator,
    ///         "operator1-passphrase".to_string(),
    ///         Some("user1".to_string()),
    ///     )
    ///     .is_err());
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_user(
        &self,
        real_name: String,
        role: UserRole,
        passphrase: String,
        user_id: Option<String>,
    ) -> Result<String, Error> {
        let user_id = if let Some(user_id) = user_id {
            users_user_id_put(
                &self.config.borrow(),
                &user_id,
                UserPostData::new(real_name, role, passphrase.clone()),
            )
            .map_err(|error| {
                Error::Api(format!(
                    "Adding user failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?;
            user_id
        } else {
            users_post(
                &self.config.borrow(),
                UserPostData::new(real_name, role, passphrase.clone()),
            )
            .map_err(|error| {
                Error::Api(format!(
                    "Adding user failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity
            .id
        };

        // add to list of users
        self.users
            .borrow_mut()
            .push((user_id.clone(), Some(passphrase)));

        Ok(user_id)
    }

    /// Deletes a user from the device
    ///
    /// [Deletes a user](https://docs.nitrokey.com/nethsm/administration#delete-user)
    /// from the device based on `user_id`.
    ///
    /// Internally, this function also calls [`NetHsm::remove_credentials`] to remove the user from
    /// the list of available credentials.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if deleting a user fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * 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 "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, UserRole};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // add a user in the operator role
    /// assert_eq!(
    ///     "user1",
    ///     nethsm.add_user(
    ///         "Operator One".to_string(),
    ///         UserRole::Operator,
    ///         "operator1-passphrase".to_string(),
    ///         Some("user1".to_string()),
    ///     )?
    /// );
    ///
    /// // delete the user again
    /// nethsm.delete_user("user1")?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn delete_user(&self, user_id: &str) -> Result<(), Error> {
        users_user_id_delete(&self.config.borrow(), user_id).map_err(|error| {
            Error::Api(format!(
                "Deleting user failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;

        // remove from list of credentials
        self.remove_credentials(user_id);

        Ok(())
    }

    /// Gets a list of all User IDs on the device
    ///
    /// Gets a [list of all User IDs](https://docs.nitrokey.com/nethsm/administration#list-users)
    /// on the device.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if retrieving the list of all User IDs fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get all User IDs... at a minimum the "admin" user should be there!
    /// assert!(nethsm.get_users()?.contains(&"admin".to_string()));
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_users(&self) -> Result<Vec<String>, Error> {
        Ok(users_get(&self.config.borrow())
            .map_err(|error| {
                Error::Api(format!(
                    "Getting users failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity
            .iter()
            .map(|x| x.user.clone())
            .collect())
    }

    /// Gets information of a user on the device
    ///
    /// Gets [information of a user](https://docs.nitrokey.com/nethsm/administration#list-users)
    /// on the device and returns it as a [`UserData`].
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if retrieving information of the user fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * 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 "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get user information
    /// println!("{:?}", nethsm.get_user("admin")?);
    ///
    /// // this fails as the user does not exist
    /// assert!(nethsm.get_user("user1").is_err());
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_user(&self, user_id: &str) -> Result<UserData, Error> {
        Ok(users_user_id_get(&self.config.borrow(), user_id)
            .map_err(|error| {
                Error::Api(format!(
                    "Getting user failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity)
    }

    /// Sets the passphrase for a user on the device
    ///
    /// Sets the [passphrase for a user](https://docs.nitrokey.com/nethsm/administration#user-passphrase)
    /// on the device.
    ///
    /// Internally, this function also calls [`NetHsm::add_credentials`] to add the updated user
    /// credentials to the list of available credentials.
    /// If the calling user in the "admin" role changes their own passphrase, additionally
    /// [`NetHsm::use_credentials`] is called to use the updated passphrase.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if setting the passphrase for the user fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * 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 "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // set the admin user's passphrase
    /// nethsm.set_user_passphrase("admin", "new-admin-passphrase".to_string())?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_user_passphrase(&self, user_id: &str, passphrase: String) -> Result<(), Error> {
        users_user_id_passphrase_post(
            &self.config.borrow(),
            user_id,
            UserPassphrasePostData::new(passphrase.clone()),
        )
        .map_err(|error| {
            Error::Api(format!(
                "Setting user passphrase failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;

        // add to list of available credentials
        self.add_credentials((user_id.to_string(), Some(passphrase)));
        // if the caller changed their own passphrase, use it
        if self
            .config
            .borrow()
            .basic_auth
            .as_ref()
            .is_some_and(|credentials| credentials.0 == user_id)
        {
            self.use_credentials(user_id)?;
        }

        Ok(())
    }

    /// Adds a tag to a user in the operator role
    ///
    /// [Adds a tag](https://docs.nitrokey.com/nethsm/administration#tags-for-users)
    /// to a user in the "operator" role. A tag provides a user in the "operator" role with access
    /// to keys on the device associated with that same tag. The tag must have been set for a
    /// key on the device beforehand (e.g. using [`NetHsm::add_key_tag`]).
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if adding the tag for the user fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the user identified by `user_id` does not exist
    /// * the user identified by `user_id` is not in the "operator" role
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, UserRole};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // add a user in the operator role
    /// assert_eq!(
    ///     "user1",
    ///     nethsm.add_user(
    ///         "Operator One".to_string(),
    ///         UserRole::Operator,
    ///         "operator1-passphrase".to_string(),
    ///         Some("user1".to_string()),
    ///     )?
    /// );
    ///
    /// // add a tag for the user
    /// nethsm.add_user_tag("user1", "tag1")?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_user_tag(&self, user_id: &str, tag: &str) -> Result<(), Error> {
        users_user_id_tags_tag_put(&self.config.borrow(), user_id, tag).map_err(|error| {
            Error::Api(format!(
                "Adding tag for user failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Deletes a tag from a user in the operator role
    ///
    /// [Deletes a tag](https://docs.nitrokey.com/nethsm/administration#tags-for-users)
    /// from a user in the "operator" role. Removing a tag from a user in the "operator" role
    /// removes its access to any key on the device that has the same tag.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if deleting the tag from the user fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the user identified by `user_id` does not exist
    /// * the user identified by `user_id` is not in the "operator" role
    /// * the user identified by `user_id` does not have `tag`
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, UserRole};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // add a tag for the user
    /// nethsm.delete_user_tag("user1", "tag1")?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn delete_user_tag(&self, user_id: &str, tag: &str) -> Result<(), Error> {
        users_user_id_tags_tag_delete(&self.config.borrow(), user_id, tag).map_err(|error| {
            Error::Api(format!(
                "Deleting tag for user failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Gets all tags on a user in the operator role
    ///
    /// [Gets all tags](https://docs.nitrokey.com/nethsm/administration#tags-for-users)
    /// of a user in the operator role.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if getting the tags for the user fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the user identified by `user_id` does not exist
    /// * the user identified by `user_id` is not in the "operator" role
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, UserRole};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // add a user in the operator role
    /// assert_eq!(
    ///     "user1",
    ///     nethsm.add_user(
    ///         "Operator One".to_string(),
    ///         UserRole::Operator,
    ///         "operator1-passphrase".to_string(),
    ///         Some("user1".to_string()),
    ///     )?
    /// );
    ///
    /// assert!(nethsm.get_user_tags("user1")?.is_empty());
    ///
    /// // add a tag for the user
    /// nethsm.add_user_tag("user1", "tag1")?;
    ///
    /// assert!(nethsm.get_user_tags("user1")?.contains(&"tag1".to_string()));
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_user_tags(&self, user_id: &str) -> Result<Vec<String>, Error> {
        Ok(users_user_id_tags_get(&self.config.borrow(), user_id)
            .map_err(|error| {
                Error::Api(format!(
                    "Getting tags of user failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity)
    }

    /// Generates a new key on the device
    ///
    /// [Generates a new key](https://docs.nitrokey.com/nethsm/operation#generate-key)
    /// with custom features on the device.
    /// The provided [`KeyType`] and list of [`KeyMechanism`]s 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::RsaSignaturePssMd5`], [`KeyMechanism::RsaSignaturePssSha1`],
    ///   [`KeyMechanism::RsaSignaturePssSha224`], [`KeyMechanism::RsaSignaturePssSha256`],
    ///   [`KeyMechanism::RsaSignaturePssSha384`] or [`KeyMechanism::RsaSignaturePssSha512`]
    /// * [`KeyType::Curve25519`] requires [`KeyMechanism::EdDsaSignature`]
    /// * [`KeyType::EcP224`], [`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 (using `tags`) can be provided.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if generating the key fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the provided combination of `key_type` and `mechanisms` is not valid
    /// * 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 "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, KeyMechanism, KeyType, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-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".to_string()),
    ///     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(4096),
    ///     Some("encryption1".to_string()),
    ///     Some(vec!["encryption_tag1".to_string()]),
    /// )?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn generate_key(
        &self,
        key_type: KeyType,
        mechanisms: Vec<KeyMechanism>,
        length: Option<i32>,
        key_id: Option<String>,
        tags: Option<Vec<String>>,
    ) -> Result<String, Error> {
        // ensure the key_type - mechanisms combinations are valid
        match_key_type_and_mechanisms(key_type, &mechanisms)?;

        Ok(keys_generate_post(
            &self.config.borrow(),
            KeyGenerateRequestData {
                mechanisms,
                r#type: key_type,
                length,
                id: key_id,
                restrictions: tags.map(|tags| Box::new(KeyRestrictions { tags: Some(tags) })),
            },
        )
        .map_err(|error| {
            Error::Api(format!(
                "Creating key failed: {}",
                NetHsmApiError::from(error)
            ))
        })?
        .entity
        .id)
    }

    /// Imports an existing private key
    ///
    /// [Imports an existing key](https://docs.nitrokey.com/nethsm/operation#import-key)
    /// with custom features into the device.
    /// The provided [`KeyType`] and list of [`KeyMechanism`]s 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::RsaSignaturePssMd5`], [`KeyMechanism::RsaSignaturePssSha1`],
    ///   [`KeyMechanism::RsaSignaturePssSha224`], [`KeyMechanism::RsaSignaturePssSha256`],
    ///   [`KeyMechanism::RsaSignaturePssSha384`] or [`KeyMechanism::RsaSignaturePssSha512`]
    /// * [`KeyType::Curve25519`] requires [`KeyMechanism::EdDsaSignature`]
    /// * [`KeyType::EcP224`], [`KeyType::EcP256`], [`KeyType::EcP384`] and [`KeyType::EcP521`]
    ///   require [`KeyMechanism::EcdsaSignature`]
    /// * [`KeyType::Generic`] requires one of [`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
    /// (using `tags`) can be provided.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if importing the key fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the provided combination of `key_type` and `mechanisms` is not valid
    /// * the provided combination of `key_type` and `key_data` is not valid
    /// * 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 "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, KeyImportData, KeyMechanism, KeyType, NetHsm};
    /// use rsa::traits::PrivateKeyParts;
    /// use rsa::traits::PublicKeyParts;
    /// use rsa::RsaPrivateKey;
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // create an RSA private key and only extract prime p, q and the public exponent
    /// // (for import)
    /// let (prime_p, prime_q, public_exponent) = {
    ///     let mut rng = rand::thread_rng();
    ///     let private_key = RsaPrivateKey::new(&mut rng, 4096).unwrap();
    ///     let (prime_p, prime_q, public_exponent) = (
    ///         private_key.primes().first().unwrap(),
    ///         private_key.primes().get(1).unwrap(),
    ///         private_key.e(),
    ///     );
    ///     (
    ///         Some(prime_p.to_bytes_be()),
    ///         Some(prime_q.to_bytes_be()),
    ///         Some(public_exponent.to_bytes_be()),
    ///     )
    /// };
    /// // import an RSA key for PKCS1 signatures
    /// nethsm.import_key(
    ///     KeyType::Rsa,
    ///     vec![KeyMechanism::RsaSignaturePkcs1],
    ///     Box::new(KeyImportData {
    ///         prime_p,
    ///         prime_q,
    ///         public_exponent,
    ///         data: None,
    ///     }),
    ///     Some("signing2".to_string()),
    ///     Some(vec!["signing_tag3".to_string()]),
    /// )?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn import_key(
        &self,
        key_type: KeyType,
        mechanisms: Vec<KeyMechanism>,
        key_data: Box<KeyImportData>,
        key_id: Option<String>,
        tags: Option<Vec<String>>,
    ) -> Result<String, Error> {
        // ensure the key_type - mechanisms combinations are valid
        match_key_type_and_mechanisms(key_type, &mechanisms)?;

        // ensure the key_type - key_data combination is valid
        key_data.validate_key_type(key_type)?;

        let restrictions = tags.map(|tags| Box::new(KeyRestrictions { tags: Some(tags) }));
        let private = key_data.into();

        if let Some(key_id) = key_id {
            keys_key_id_put(
                &self.config.borrow(),
                &key_id,
                nethsm_sdk_rs::apis::default_api::KeysKeyIdPutBody::ApplicationJson(PrivateKey {
                    mechanisms,
                    r#type: key_type,
                    private,
                    restrictions,
                }),
            )
            .map_err(|error| {
                Error::Api(format!(
                    "Importing key failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?;
            Ok(key_id)
        } else {
            Ok(keys_post(
                &self.config.borrow(),
                KeysPostBody::ApplicationJson(PrivateKey {
                    mechanisms,
                    r#type: key_type,
                    private,
                    restrictions,
                }),
            )
            .map_err(|error| {
                Error::Api(format!(
                    "Importing key failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity
            .id)
        }
    }

    /// Deletes a key from the device
    ///
    /// [Deletes a key](https://docs.nitrokey.com/nethsm/operation#delete-key)
    /// from the device based on a Key ID provided using `key_id`.
    ///
    /// This call requires using credentials of a user in the "admin" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if deleting the key fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * no key identified by `key_id` exists
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // delete a key with the Key ID "signing1"
    /// assert!(nethsm.delete_key("signing1").is_ok());
    /// # Ok(())
    /// # }
    /// ```
    pub fn delete_key(&self, key_id: &str) -> Result<(), Error> {
        keys_key_id_delete(&self.config.borrow(), key_id).map_err(|error| {
            Error::Api(format!(
                "Deleting key failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Gets details of a key
    ///
    /// [Gets details of a key](https://docs.nitrokey.com/nethsm/operation#show-key-details)
    /// from the device based on a Key ID provided using `key_id`.
    ///
    /// This call requires using credentials of a user in the "admin" or "operator"
    /// [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if getting the key details fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * no key identified by `key_id` exists
    /// * the used credentials are not correct
    /// * the used credentials are not those of a user in the "admin" or "operator" role
    /// * a user in the "operator" role lacks access to the key
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get details on a key with the Key ID "signing1"
    /// println!("{:?}", nethsm.get_key("signing1")?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_key(&self, key_id: &str) -> Result<PublicKey, Error> {
        Ok(keys_key_id_get(&self.config.borrow(), key_id)
            .map_err(|error| {
                Error::Api(format!(
                    "Getting key failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity)
    }

    /// Gets a list of Key IDs on the device
    ///
    /// [Gets a list of Key IDs](https://docs.nitrokey.com/nethsm/operation#list-keys)
    /// from the device.
    /// Optionally `filter` can be provided for matching against Key IDs.
    ///
    /// This call requires using credentials of a user in the "admin" or "operator"
    /// [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if getting the list of Key IDs fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not those of a user in the "admin" or "operator" role
    /// * a user in the "operator" role lacks access to the key
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-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"))?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_keys(&self, filter: Option<&str>) -> Result<Vec<String>, Error> {
        Ok(keys_get(&self.config.borrow(), filter)
            .map_err(|error| {
                Error::Api(format!(
                    "Getting keys failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity
            .iter()
            .map(|x| x.id.clone())
            .collect())
    }

    /// Gets the public key of a key on the device
    ///
    /// [Gets the public key of a key](https://docs.nitrokey.com/nethsm/operation#show-key-details)
    /// on the device specified by `key_id`.
    /// The public key is returned in PKCS#8 format.
    ///
    /// This call requires using credentials of a user in the "admin" or "operator"
    /// [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if getting the public key fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * no key identified by `key_id` exists
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" or "operator" role
    /// * a user in the "operator" role lacks access to the key
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get public key for a key with Key ID "signing1"
    /// println!("{:?}", nethsm.get_public_key("signing1")?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_public_key(&self, key_id: &str) -> Result<String, Error> {
        Ok(keys_key_id_public_pem_get(&self.config.borrow(), key_id)
            .map_err(|error| {
                Error::Api(format!(
                    "Getting public key failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity)
    }

    /// Adds a tag to a key on the device
    ///
    /// [Adds a tag to a key](https://docs.nitrokey.com/nethsm/operation#tags-for-keys)
    /// on the device.
    /// The key is specified by `key_id` and the tag using `tag`.
    ///
    /// Afterwards the same `tag` can be associated with a user in the "operator" role, using
    /// [`NetHsm::add_user_tag`] to provide the user access to the respective key(s).
    ///
    /// This call requires using credentials of a user in the "admin"
    /// [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if adding a tag to a key fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * 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 "admin" or "operator" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // add the tag "important" to a key with Key ID "signing1"
    /// nethsm.add_key_tag("signing1", "important")?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_key_tag(&self, key_id: &str, tag: &str) -> Result<(), Error> {
        keys_key_id_restrictions_tags_tag_put(&self.config.borrow(), tag, key_id).map_err(
            |error| {
                Error::Api(format!(
                    "Adding tag for key failed: {}",
                    NetHsmApiError::from(error)
                ))
            },
        )?;
        Ok(())
    }

    /// Deletes a tag from a key on the device
    ///
    /// [Deletes a tag from a key](https://docs.nitrokey.com/nethsm/operation#tags-for-keys)
    /// on the device. Any user in the "operator" role that has the same tag will lose access to the
    /// affected key.
    ///
    /// This call requires using credentials of a user in the "admin"
    /// [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if adding a tag to a key fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * 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 "admin" or "operator" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, KeyImportData, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // remove the tag "important" from a key with Key ID "signing1"
    /// nethsm.delete_key_tag("signing1", "important")?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn delete_key_tag(&self, key_id: &str, tag: &str) -> Result<(), Error> {
        keys_key_id_restrictions_tags_tag_delete(&self.config.borrow(), tag, key_id).map_err(
            |error| {
                Error::Api(format!(
                    "Deleting tag for key failed: {}",
                    NetHsmApiError::from(error)
                ))
            },
        )?;
        Ok(())
    }

    /// Imports a certificate for a key
    ///
    /// [Imports a certificate](https://docs.nitrokey.com/nethsm/operation#key-certificates)
    /// and associates it with a key on the device.
    /// Certificates are supported as the following MIME types:
    /// * *application/x-pem-file*
    /// * *application/x-x509-ca-cert*
    /// * *application/pgp-keys*
    ///
    /// This call requires using credentials of a user in the "admin"
    /// [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if adding a tag to a key fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * 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 "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// let cert_data = r#"
    /// -----BEGIN CERTIFICATE-----
    /// MIICeTCCAWECFCbuzdkAvc3Zx3W53IoSnmhUen42MA0GCSqGSIb3DQEBCwUAMHsx
    /// CzAJBgNVBAYTAkRFMQ8wDQYDVQQIDAZCZXJsaW4xDzANBgNVBAcMBkJlcmxpbjER
    /// MA8GA1UECgwITml0cm9rZXkxFTATBgNVBAMMDG5pdHJva2V5LmNvbTEgMB4GCSqG
    /// SIb3DQEJARYRaW5mb0BuaXRyb2tleS5jb20wHhcNMjIwODMwMjAxMzA2WhcNMjMw
    /// ODMwMjAxMzA2WjBxMW8wCQYDVQQGEwJERTANBgNVBAcMBkJlcmxpbjANBgNVBAgM
    /// BkJlcmxpbjAPBgNVBAoMCE5pdHJva2V5MBMGA1UEAwwMbml0cm9rZXkuY29tMB4G
    /// CSqGSIb3DQEJARYRaW5mb0BuaXRyb2tleS5jb20wKjAFBgMrZXADIQDc58LGDY9B
    /// wbJFdXTiDalNXrDC60Sxu3eHcpnh1MSoCjANBgkqhkiG9w0BAQsFAAOCAQEAGip8
    /// aU5nJnzm3eic3t1ihUA3VJ0mAPyfrb1Rn8tEKOZo3vg0jpRd9CSESlBsKqhvxsdQ
    /// A3eomM+W7R37TL5+ISm5QrbijLHz3OHoPM68c1Krz3bXTkJetf4YAxpLOPYfXXHv
    /// weRzwVJb4y3E0lJGhZxI3sUE8Yn/T1UvTbu/o/O5P/XTA8vfFrSNQkQxWBgYh4gC
    /// KjFFALqUPFrctSFIi34aqpdihNJWnjSS2Y7INm3oxwkR3NMKP8x4wBGfZK22nHnu
    /// PPzXuMGJTmQM8GHTzltNvLx5Iv2sXoSHClXSpdIT5IBIcR1GmZ78fmcr75OAU0+z
    /// 3XbJq/1ij3tKsjV6WA==
    /// -----END CERTIFICATE-----
    /// "#
    /// .to_string();
    ///
    /// // import a certificate for a key with Key ID "signing1"
    /// nethsm.import_key_certificate("signing1", cert_data.into_bytes())?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn import_key_certificate(&self, key_id: &str, data: Vec<u8>) -> Result<(), Error> {
        keys_key_id_cert_put(&self.config.borrow(), key_id, data).map_err(|error| {
            Error::Api(format!(
                "Importing certificate for key failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Gets the certificate associated with a key
    ///
    /// [Gets the certificate](https://docs.nitrokey.com/nethsm/operation#key-certificates)
    /// associated with a key on the device.
    ///
    /// This call requires using credentials of a user in the "admin" or "operator"
    /// [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if adding a tag to a key fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * no key identified by `key_id` exists
    /// * no certificate is associated with the key
    /// * the user lacks access to the key
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" or "operator" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get the certificate associated with a key
    /// println!("{:?}", nethsm.get_key_certificate("signing1")?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_key_certificate(&self, key_id: &str) -> Result<Vec<u8>, Error> {
        Ok(keys_key_id_cert_get(&self.config.borrow(), key_id)
            .map_err(|error| {
                Error::Api(format!(
                    "Getting certificate for key failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity)
    }

    /// Deletes the certificate associated with a key
    ///
    /// [Deletes a certificate](https://docs.nitrokey.com/nethsm/operation#key-certificates)
    /// associated with a key on the device.
    ///
    /// This call requires using credentials of a user in the "admin"
    /// [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if adding a tag to a key fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * 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 "admin" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // delete a certificate for a key with Key ID "signing1"
    /// nethsm.delete_key_certificate("signing1")?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn delete_key_certificate(&self, key_id: &str) -> Result<(), Error> {
        keys_key_id_cert_delete(&self.config.borrow(), key_id).map_err(|error| {
            Error::Api(format!(
                "Deleting certificate for key failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Gets a Certificate Signing Request (CSR) for a key
    ///
    /// Based on data from an instance of [`nethsm_sdk_rs::models::DistinguishedName`] returns a
    /// [Certificate Signing Request (CSR)](https://en.wikipedia.org/wiki/Certificate_signing_request)
    /// in [PKCS#10](https://en.wikipedia.org/wiki/Certificate_signing_request#Structure_of_a_PKCS_#10_CSR) format
    /// for [a certificate](https://docs.nitrokey.com/nethsm/operation#key-certificate-signing-requests)
    /// associated with a key on the device.
    ///
    /// This call requires using credentials of a user in the "admin" or "operator"
    /// [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if adding a tag to a key fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * no key identified by `key_id` exists
    /// * no certificate is associated with the key
    /// * the user lacks access to the key
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "admin" or "operator" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, DistinguishedName, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get a CSR for a certificate associated with a key
    /// println!(
    ///     "{}",
    ///     nethsm.get_key_csr(
    ///         "signing1",
    ///         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()),
    ///         }
    ///     )?
    /// );
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_key_csr(
        &self,
        key_id: &str,
        distinguished_name: DistinguishedName,
    ) -> Result<String, Error> {
        Ok(
            keys_key_id_csr_pem_post(&self.config.borrow(), key_id, distinguished_name)
                .map_err(|error| {
                    Error::Api(format!(
                        "Getting CSR for key failed: {}",
                        NetHsmApiError::from(error)
                    ))
                })?
                .entity,
        )
    }

    /// Signs a message using a key
    ///
    /// [Signs](https://docs.nitrokey.com/nethsm/operation#sign) a `message` using a key
    /// identified by `key_id` and a specific `signature_type`.
    ///
    /// The `message` does not have to be hashed, as this function takes care of this based on the
    /// provided [`SignatureType`].
    ///
    /// This call requires using credentials of a user in the "operator"
    /// [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if signing the message fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * no key identified by `key_id` exists on the device
    /// * the chosen [`SignatureType`] is incompatible with the targeted key
    /// * the user lacks access to the key
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "operator" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, SignatureType};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // create an ed25519 signature
    /// // this assumes the key with Key ID "signing1" is of type KeyType::Curve25519
    /// println!(
    ///     "{:?}",
    ///     nethsm.sign("signing1", SignatureType::EdDsa, b"message")?
    /// );
    /// # Ok(())
    /// # }
    /// ```
    pub fn sign(
        &self,
        key_id: &str,
        signature_type: SignatureType,
        message: &[u8],
    ) -> Result<Vec<u8>, Error> {
        // Some algorithms require the data to be hashed first
        // The API requires data to be base64 encoded
        let message = match signature_type {
            SignatureType::Pkcs1 | SignatureType::PssSha256 | SignatureType::EcdsaP256 => {
                let mut hasher = Sha256::new();
                hasher.update(message);
                Base64::encode_string(&hasher.finalize()[..])
            }
            SignatureType::PssMd5 => {
                let mut hasher = Md5::new();
                hasher.update(message);
                Base64::encode_string(&hasher.finalize()[..])
            }
            SignatureType::PssSha1 => {
                let mut hasher = Sha1::new();
                hasher.update(message);
                Base64::encode_string(&hasher.finalize()[..])
            }
            SignatureType::PssSha224 | SignatureType::EcdsaP224 => {
                let mut hasher = Sha224::new();
                hasher.update(message);
                Base64::encode_string(&hasher.finalize()[..])
            }
            SignatureType::PssSha384 | SignatureType::EcdsaP384 => {
                let mut hasher = Sha384::new();
                hasher.update(message);
                Base64::encode_string(&hasher.finalize()[..])
            }
            SignatureType::PssSha512 | SignatureType::EcdsaP521 => {
                let mut hasher = Sha512::new();
                hasher.update(message);
                Base64::encode_string(&hasher.finalize()[..])
            }
            SignatureType::EdDsa => Base64::encode_string(message),
        };

        // decode base64 encoded data from the API
        Base64::decode_vec(
            &keys_key_id_sign_post(
                &self.config.borrow(),
                key_id,
                SignRequestData::new(signature_type.into(), message),
            )
            .map_err(|error| {
                Error::Api(format!(
                    "Signing message failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity
            .signature,
        )
        .map_err(Error::Base64Decode)
    }

    /// Encrypts a message using a symmetric key
    ///
    /// [Encrypts](https://docs.nitrokey.com/nethsm/operation#encrypt) 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 mechanism
    /// [`KeyMechanism::AesDecryptionCbc`] and [`KeyMechanism::AesEncryptionCbc`].
    ///
    /// This call requires using credentials of a user in the "operator"
    /// [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if signing the message fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * no key identified by `key_id` exists on the device
    /// * the chosen `mode` is incompatible with the targeted key
    /// * the user lacks access to the key
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "operator" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, EncryptMode, Error, NetHsm};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // 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("signing1", EncryptMode::AesCbc, message, Some(iv))?
    /// );
    /// # Ok(())
    /// # }
    /// ```
    pub fn encrypt(
        &self,
        key_id: &str,
        mode: EncryptMode,
        message: &[u8],
        iv: Option<&[u8]>,
    ) -> Result<Vec<u8>, Error> {
        // the API requires data to be base64 encoded
        let message = Base64::encode_string(message);
        let iv = iv.map(Base64::encode_string);

        // decode base64 encoded data from the API
        Base64::decode_vec(
            &keys_key_id_encrypt_post(
                &self.config.borrow(),
                key_id,
                EncryptRequestData { mode, message, iv },
            )
            .map_err(|error| {
                Error::Api(format!(
                    "Encrypting message failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity
            .encrypted,
        )
        .map_err(Error::Base64Decode)
    }

    /// Decrypts a message using a key
    ///
    /// [Decrypts](https://docs.nitrokey.com/nethsm/operation#decrypt) 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
    /// [`NetHsm::encrypt`]) by providing [`DecryptMode::AesCbc`] as `mode`. The targeted key must
    /// be of type [`KeyType::Generic`] and feature the mechanism
    /// [`KeyMechanism::AesDecryptionCbc`] and [`KeyMechanism::AesEncryptionCbc`].
    ///
    /// Decryption for messages encrypted using asymmetric keys is also possible. Foreign entities
    /// can use the public key of an asymmetric key (see [`NetHsm::get_public_key`]) to encrypt a
    /// message and the private key on the device is used for decryption.
    ///
    /// This call requires using credentials of a user in the "operator"
    /// [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if signing the message fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * no key identified by `key_id` exists on the device
    /// * the chosen `mode` is incompatible with the targeted key
    /// * the user lacks access to the key
    /// * the encrypted message can not be decrypted
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "operator" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, DecryptMode, EncryptMode, Error, NetHsm};
    /// use rsa::pkcs8::DecodePublicKey;
    /// use rsa::Pkcs1v15Encrypt;
    /// use rsa::RsaPublicKey;
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "admin" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("admin".to_string(), Some("admin-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // 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
    /// let encrypted_message = nethsm.encrypt("encryption1", 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", 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")?).unwrap();
    /// let mut rng = rand::thread_rng();
    /// let encrypted_message = pubkey.encrypt(&mut rng, Pkcs1v15Encrypt, message.as_bytes()).unwrap();
    /// println!("raw encrypted message: {:?}", encrypted_message);
    ///
    /// let decrypted_message =
    ///     nethsm.decrypt("encryption2", DecryptMode::Pkcs1, &encrypted_message, None)?;
    /// println!("raw decrypted message: {:?}", decrypted_message);
    ///
    /// assert_eq!(&decrypted_message, message.as_bytes());
    /// # Ok(())
    /// # }
    /// ```
    pub fn decrypt(
        &self,
        key_id: &str,
        mode: DecryptMode,
        message: &[u8],
        iv: Option<&[u8]>,
    ) -> Result<Vec<u8>, Error> {
        // the API requires data to be base64 encoded
        let encrypted = Base64::encode_string(message);
        let iv = iv.map(Base64::encode_string);

        // decode base64 encoded data from the API
        Base64::decode_vec(
            &keys_key_id_decrypt_post(
                &self.config.borrow(),
                key_id,
                DecryptRequestData {
                    mode,
                    encrypted,
                    iv,
                },
            )
            .map_err(|error| {
                Error::Api(format!(
                    "Decrypting message failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity
            .decrypted,
        )
        .map_err(Error::Base64Decode)
    }

    /// Get random bytes
    ///
    /// Retrieves `length` [random](https://docs.nitrokey.com/nethsm/operation#random) bytes
    /// from the device, if it is in state [`SystemState::Operational`].
    ///
    /// This call requires using credentials of a user in the "operator" [role](https://docs.nitrokey.com/nethsm/administration#roles).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if retrieving random bytes fails:
    /// * the device is not in state [`SystemState::Operational`]
    /// * the used credentials are not correct
    /// * the used credentials are not that of a user in the "operator" role
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{ConnectionSecurity, Error, NetHsm, SystemState};
    ///
    /// # fn main() -> Result<(), Error> {
    /// // create a connection with a user in the "operator" role
    /// let nethsm = NetHsm::new(
    ///     "https://example.org/api/v1".to_string(),
    ///     ConnectionSecurity::Unsafe,
    ///     Some(("user1".to_string(), Some("user1-passphrase".to_string()))),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// assert_eq!(nethsm.state()?, SystemState::Operational);
    /// // get 10 random bytes
    /// println!("{:#?}", nethsm.random(10)?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn random(&self, length: i32) -> Result<Vec<u8>, Error> {
        let base64_bytes = random_post(&self.config.borrow(), RandomRequestData::new(length))
            .map_err(|error| {
                Error::Api(format!(
                    "Getting random bytes failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity
            .random;
        Base64::decode_vec(&base64_bytes).map_err(Error::Base64Decode)
    }
}