nethsm/base/

impl_key.rs

//! [`NetHsm`] implementation for cryptographic key support.

use base64ct::{Base64, Encoding};
use log::debug;
use nethsm_sdk_rs::{
    apis::default_api::{
        KeysKeyIdPutBody,
        KeysPostBody,
        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,
    },
    models::{
        DecryptRequestData,
        DistinguishedName,
        EncryptRequestData,
        KeyGenerateRequestData,
        KeyRestrictions,
        PrivateKey,
        PublicKey,
        SignRequestData,
    },
};
use sha1::Sha1;
use sha2::{Digest, Sha224, Sha256, Sha384, Sha512};

#[cfg(doc)]
use crate::{Credentials, SystemState, UserRole};
use crate::{
    DecryptMode,
    EncryptMode,
    Error,
    KeyId,
    KeyMechanism,
    KeyType,
    NetHsm,
    PrivateKeyImport,
    SignatureType,
    base::utils::user_or_no_user_string,
    key_type_matches_length,
    key_type_matches_mechanisms,
    nethsm_sdk::NetHsmApiError,
    user::NamespaceSupport,
};

impl NetHsm {
    /// [Generates a new key] on the NetHSM.
    ///
    /// [Generates a new key] with customizable features on the NetHSM.
    /// 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::RsaSignaturePssSha1`], [`KeyMechanism::RsaSignaturePssSha224`],
    ///   [`KeyMechanism::RsaSignaturePssSha256`], [`KeyMechanism::RsaSignaturePssSha384`] or
    ///   [`KeyMechanism::RsaSignaturePssSha512`]
    /// * [`KeyType::Curve25519`] requires [`KeyMechanism::EdDsaSignature`]
    /// * [`KeyType::EcP256`], [`KeyType::EcP384`] and [`KeyType::EcP521`] require
    ///   [`KeyMechanism::EcdsaSignature`]
    /// * [`KeyType::Generic`] requires one of [`KeyMechanism::AesDecryptionCbc`] or
    ///   [`KeyMechanism::AesEncryptionCbc`]
    ///
    /// Optionally the key bit-length using `length`, a custom key ID using `key_id`
    /// and a list of `tags` to be attached to the new key can be provided.
    /// If no `key_id` is provided, a unique one is generated automatically.
    ///
    /// **WARNING**: If no `tags` are provided, the generated key is usable by all users in the
    /// [`Operator`][`UserRole::Operator`] [role] in the same scope (e.g. same [namespace]) by
    /// default!
    ///
    /// This call requires using [`Credentials`] of a user in the
    /// [`Administrator`][`UserRole::Administrator`] [role].
    ///
    /// ## Namespaces
    ///
    /// * Keys generated by *N-Administrators* ([`Administrator`][`UserRole::Administrator`] users
    ///   in a given [namespace]) are only visible to users in their [namespace]. Only users in the
    ///   [`Operator`][`UserRole::Operator`] [role] in that same [namespace] can be granted access
    ///   to them.
    /// * Keys generated by *R-Administrators* (system-wide
    ///   [`Administrator`][`UserRole::Administrator`] users) are only visible to system-wide users.
    ///   Only system-wide users in the [`Operator`][`UserRole::Operator`] [role] (not in any
    ///   [namespace]) can be granted access to them.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if generating the key fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * a key identified by ` key_id` exists already
    /// * the chosen `length` or `tags` options are not valid
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not that of a user in the
    ///   [`Administrator`][`UserRole::Administrator`] [role]
    ///
    /// Returns an [`Error::Key`] if
    /// * the provided combination of `key_type` and `mechanisms` is not valid.
    /// * the provided combination of `key_type` and `length` is not valid.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{
    ///     Connection,
    ///     ConnectionSecurity,
    ///     Credentials,
    ///     KeyMechanism,
    ///     KeyType,
    ///     NetHsm,
    ///     Passphrase,
    /// };
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // generate a Curve25519 key for signing with custom Key ID and tags
    /// nethsm.generate_key(
    ///     KeyType::Curve25519,
    ///     vec![KeyMechanism::EdDsaSignature],
    ///     None,
    ///     Some("signing1".parse()?),
    ///     Some(vec!["sign_tag1".to_string(), "sign_tag2".to_string()]),
    ///     Some("label1".to_string()),
    /// )?;
    ///
    /// // generate a generic key for symmetric encryption and decryption
    /// nethsm.generate_key(
    ///     KeyType::Generic,
    ///     vec![
    ///         KeyMechanism::AesEncryptionCbc,
    ///         KeyMechanism::AesDecryptionCbc,
    ///     ],
    ///     Some(128),
    ///     Some("encryption1".parse()?),
    ///     Some(vec!["encryption_tag1".to_string()]),
    ///     Some("label2".to_string()),
    /// )?;
    /// # Ok(())
    /// # }
    /// ```
    /// [Generates a new key]: https://docs.nitrokey.com/nethsm/operation#generate-key
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn generate_key(
        &self,
        key_type: KeyType,
        mechanisms: Vec<KeyMechanism>,
        length: Option<u32>,
        key_id: Option<KeyId>,
        tags: Option<Vec<String>>,
        label: Option<String>,
    ) -> Result<KeyId, Error> {
        debug!(
            "Generate a key (key type: {key_type}; mechanisms: {}; length: {}; ID: {}, tags: {}) on the NetHSM at {} using {}",
            mechanisms
                .iter()
                .map(|mechanism| mechanism.to_string())
                .collect::<Vec<String>>()
                .join(", "),
            if let Some(length) = length {
                length.to_string()
            } else {
                "n/a".to_string()
            },
            if let Some(key_id) = key_id.as_ref() {
                key_id.to_string()
            } else {
                "n/a".to_string()
            },
            if let Some(tags) = tags.as_ref() {
                tags.join(", ")
            } else {
                "n/a".to_string()
            },
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        // ensure the key_type - mechanisms combinations are valid
        key_type_matches_mechanisms(key_type, &mechanisms)?;
        // ensure the key_type - length combination is valid
        key_type_matches_length(key_type, length)?;

        // WARNING: Upstream has decided to set all models non-exhaustive.
        //
        // On each update to nethsm-sdk-rs, check whether KeyGenerateRequestData has gained further
        // fields.
        let key_generate_request_data = {
            let mut key_generate_request_data = KeyGenerateRequestData::new(
                mechanisms
                    .into_iter()
                    .map(|mechanism| mechanism.into())
                    .collect(),
                key_type.try_into()?,
            );
            key_generate_request_data.length = length.map(|length| length as i32);
            key_generate_request_data.id = key_id.map(Into::into);
            key_generate_request_data.restrictions = tags.map(|tags| {
                let mut key_restrictions = KeyRestrictions::new();
                key_restrictions.tags = Some(tags);
                Box::new(key_restrictions)
            });
            key_generate_request_data.label = label;
            key_generate_request_data
        };

        Ok(
            keys_generate_post(&self.create_connection_config(), key_generate_request_data)
                .map_err(|error| {
                    Error::Api(format!(
                        "Creating key failed: {}",
                        NetHsmApiError::from(error)
                    ))
                })?
                .entity
                .id
                .parse()?,
        )
    }

    /// Imports an existing private key.
    ///
    /// [Imports an existing key] with custom features into the NetHSM.
    /// The [`KeyType`] implied by the provided [`PrivateKeyImport`] and the list of
    /// [`KeyMechanism`]s have to match:
    /// * [`KeyType::Rsa`] must be used with [`KeyMechanism::RsaDecryptionRaw`],
    ///   [`KeyMechanism::RsaDecryptionPkcs1`], [`KeyMechanism::RsaDecryptionOaepMd5`],
    ///   [`KeyMechanism::RsaDecryptionOaepSha1`], [`KeyMechanism::RsaDecryptionOaepSha224`],
    ///   [`KeyMechanism::RsaDecryptionOaepSha256`], [`KeyMechanism::RsaDecryptionOaepSha384`],
    ///   [`KeyMechanism::RsaDecryptionOaepSha512`], [`KeyMechanism::RsaSignaturePkcs1`],
    ///   [`KeyMechanism::RsaSignaturePssSha1`], [`KeyMechanism::RsaSignaturePssSha224`],
    ///   [`KeyMechanism::RsaSignaturePssSha256`], [`KeyMechanism::RsaSignaturePssSha384`] or
    ///   [`KeyMechanism::RsaSignaturePssSha512`]
    /// * [`KeyType::Curve25519`] must be used with [`KeyMechanism::EdDsaSignature`]
    /// * [`KeyType::EcP256`], [`KeyType::EcP384`] and [`KeyType::EcP521`] must be used with
    ///   [`KeyMechanism::EcdsaSignature`]
    /// * [`KeyType::Generic`] must be used with [`KeyMechanism::AesDecryptionCbc`] or
    ///   [`KeyMechanism::AesEncryptionCbc`]
    ///
    /// Optionally a custom Key ID using `key_id` and a list of `tags` to be attached to the new key
    /// can be provided.
    /// If no `key_id` is provided, a unique one is generated automatically.
    ///
    /// **WARNING**: If no `tags` are provided, the imported key is usable by all users in the
    /// [`Operator`][`UserRole::Operator`] [role] in the same scope (e.g. same [namespace]) by
    /// default!
    ///
    /// This call requires using [`Credentials`] of a user in the
    /// [`Administrator`][`UserRole::Administrator`] [role].
    ///
    /// ## Namespaces
    ///
    /// * Keys imported by *N-Administrators* ([`Administrator`][`UserRole::Administrator`] users in
    ///   a given [namespace]) are only visible to users in their [namespace]. Only users in the
    ///   [`Operator`][`UserRole::Operator`] [role] in that same [namespace] can be granted access
    ///   to them.
    /// * Keys imported by *R-Administrators* (system-wide
    ///   [`Administrator`][`UserRole::Administrator`] users) are only visible to system-wide users.
    ///   Only system-wide users in the [`Operator`][`UserRole::Operator`] [role] (not in any
    ///   [namespace]) can be granted access to them.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if importing the key fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * a key identified by ` key_id` exists already
    /// * the chosen `tags` option is not valid
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not that of a user in the
    ///   [`Administrator`][`UserRole::Administrator`] [role]
    ///
    /// Returns an [`Error::Key`] if the provided combination of `key_data` and `mechanisms` is not
    /// valid.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{Connection, ConnectionSecurity, Credentials, PrivateKeyImport, KeyMechanism, KeyType, NetHsm, Passphrase};
    /// use rand::{SeedableRng, rngs::ChaCha20Rng, rng};
    /// use rsa::pkcs8::{DecodePrivateKey, EncodePrivateKey};
    /// use rsa::RsaPrivateKey;
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // create a 4096 bit RSA private key and return it as PKCS#8 private key in ASN.1 DER-encoded format
    /// let private_key = {
    ///     let private_key = RsaPrivateKey::new(&mut ChaCha20Rng::from_rng(&mut rng()), 4096)?;
    ///     private_key.to_pkcs8_der()?
    /// };
    ///
    /// // import an RSA key for PKCS1 signatures
    /// nethsm.import_key(
    ///     vec![KeyMechanism::RsaSignaturePkcs1],
    ///     PrivateKeyImport::new(KeyType::Rsa, private_key.as_bytes())?,
    ///     Some("signing2".parse()?),
    ///     Some(vec!["signing_tag3".to_string()]),
    ///     Some("label3".to_string()),
    /// )?;
    /// # Ok(())
    /// # }
    /// ```
    /// [Imports an existing key]: https://docs.nitrokey.com/nethsm/operation#import-key
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn import_key(
        &self,
        mechanisms: Vec<KeyMechanism>,
        key_data: PrivateKeyImport,
        key_id: Option<KeyId>,
        tags: Option<Vec<String>>,
        label: Option<String>,
    ) -> Result<KeyId, Error> {
        debug!(
            "Import a key (mechanisms: {}; ID: {}, tags: {}) to the NetHSM at {} using {}",
            mechanisms
                .iter()
                .map(|mechanism| mechanism.to_string())
                .collect::<Vec<String>>()
                .join(", "),
            if let Some(key_id) = key_id.as_ref() {
                key_id.to_string()
            } else {
                "n/a".to_string()
            },
            if let Some(tags) = tags.as_ref() {
                tags.join(", ")
            } else {
                "n/a".to_string()
            },
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        // ensure the key_type - mechanisms combinations are valid
        let key_type = key_data.key_type();
        key_type_matches_mechanisms(key_type, &mechanisms)?;

        // WARNING: Upstream has decided to set all models non-exhaustive.
        //
        // On each update to nethsm-sdk-rs, check whether KeyRestrictions has gained further
        // fields.
        let restrictions = tags.map(|tags| {
            let mut key_restrictions = KeyRestrictions::new();
            key_restrictions.tags = Some(tags);
            Box::new(key_restrictions)
        });

        let mechanisms = mechanisms
            .into_iter()
            .map(|mechanism| mechanism.into())
            .collect();

        // WARNING: Upstream has decided to set all models non-exhaustive.
        //
        // On each update to nethsm-sdk-rs, check whether PrivateKey has gained further
        // fields.
        let private_key = {
            let mut private_key =
                PrivateKey::new(mechanisms, key_type.try_into()?, key_data.try_into()?);
            private_key.restrictions = restrictions;
            private_key.label = label;
            private_key
        };

        if let Some(key_id) = key_id {
            keys_key_id_put(
                &self.create_connection_config(),
                key_id.as_ref(),
                KeysKeyIdPutBody::ApplicationJson(private_key),
            )
            .map_err(|error| {
                Error::Api(format!(
                    "Importing key failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?;
            Ok(key_id)
        } else {
            Ok(keys_post(
                &self.create_connection_config(),
                KeysPostBody::ApplicationJson(private_key),
            )
            .map_err(|error| {
                Error::Api(format!(
                    "Importing key failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity
            .id
            .parse()?)
        }
    }

    /// [Deletes a key] from the NetHSM.
    ///
    /// [Deletes a key] identified by `key_id` from the NetHSM.
    ///
    /// This call requires using [`Credentials`] of a user in the
    /// [`Administrator`][`UserRole::Administrator`] [role].
    ///
    /// ## Namespaces
    ///
    /// * Keys in a [namespace] can only be deleted by *N-Administrators*
    ///   ([`Administrator`][`UserRole::Administrator`] users in a given [namespace]) of that
    ///   [namespace] (*R-Administrators* have no access to keys in a [namespace]). **NOTE**:
    ///   Calling [`delete_namespace`][`NetHsm::delete_namespace`] deletes **all keys** in a
    ///   [namespace]!
    /// * System-wide keys can only be deleted by *R-Administrators* (system-wide
    ///   [`Administrator`][`UserRole::Administrator`] users).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if deleting the key fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not that of a user in the
    ///   [`Administrator`][`UserRole::Administrator`] [role]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase};
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // delete a key with the Key ID "signing1"
    /// nethsm.delete_key(&"signing1".parse()?)?;
    /// # Ok(())
    /// # }
    /// ```
    /// [Deletes a key]: https://docs.nitrokey.com/nethsm/operation#delete-key
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn delete_key(&self, key_id: &KeyId) -> Result<(), Error> {
        debug!(
            "Delete the key \"{key_id}\" on the NetHSM at {} using {}",
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        keys_key_id_delete(&self.create_connection_config(), key_id.as_ref()).map_err(|error| {
            Error::Api(format!(
                "Deleting key failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Gets [details about a key].
    ///
    /// Gets [details about a key] identified by `key_id`.
    ///
    /// This call requires using [`Credentials`] of a user in the
    /// [`Administrator`][`UserRole::Administrator`] or [`Operator`][`UserRole::Operator`]
    /// [role].
    ///
    /// ## Namespaces
    ///
    /// * Users in a [namespace] can only get details about keys in their own [namespace].
    /// * System-wide users (not in a [namespace]) can only get details about system-wide keys.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if getting the key details fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not those of a user in the
    ///   [`Administrator`][`UserRole::Administrator`] or [`Operator`][`UserRole::Operator`] [role]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase};
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get details on a key with the Key ID "signing1"
    /// println!("{:?}", nethsm.get_key(&"signing1".parse()?)?);
    /// # Ok(())
    /// # }
    /// ```
    /// [details about a key]: https://docs.nitrokey.com/nethsm/operation#show-key-details
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn get_key(&self, key_id: &KeyId) -> Result<PublicKey, Error> {
        debug!(
            "Retrieve details about the key \"{key_id}\" from the NetHSM at {} using {}",
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        Ok(
            keys_key_id_get(&self.create_connection_config(), key_id.as_ref())
                .map_err(|error| {
                    Error::Api(format!(
                        "Getting key failed: {}",
                        NetHsmApiError::from(error)
                    ))
                })?
                .entity,
        )
    }

    /// Gets a [list of Key IDs] on the NetHSM.
    ///
    /// Optionally `filter` can be provided for matching against Key IDs.
    ///
    /// This call requires using [`Credentials`] of a user in the
    /// [`Administrator`][`UserRole::Administrator`] or [`Operator`][`UserRole::Operator`]
    /// [role].
    ///
    /// ## Namespaces
    ///
    /// * Users in a [namespace] can only list key IDs of keys in their own [namespace].
    /// * System-wide users (not in a [namespace]) can only list key IDs of system-wide keys.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if getting the list of Key IDs fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not those of a user in the
    ///   [`Administrator`][`UserRole::Administrator`] or [`Operator`][`UserRole::Operator`] [role]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{Connection, ConnectionSecurity, Credentials, NetHsm, Passphrase};
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    ///
    /// // get all Key IDs
    /// println!("{:?}", nethsm.get_keys(None, None)?);
    ///
    /// // get all Key IDs that begin with "signing"
    /// println!("{:?}", nethsm.get_keys(Some("signing"), None)?);
    ///
    /// // get all Key IDs that begin with "signing" and have the label "label"
    /// println!("{:?}", nethsm.get_keys(Some("signing"), Some("label"))?);
    /// # Ok(())
    /// # }
    /// ```
    /// [list of Key IDs]: https://docs.nitrokey.com/nethsm/operation#list-keys
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn get_keys(&self, filter: Option<&str>, label: Option<&str>) -> Result<Vec<KeyId>, Error> {
        debug!(
            "Get key IDs{} from the NetHSM at {} using {}",
            if let Some(filter) = filter {
                format!(" based on filter {filter}")
            } else {
                "".to_string()
            },
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        let valid_keys = {
            let mut invalid_keys = Vec::new();
            let valid_keys = keys_get(&self.create_connection_config(), filter, label)
                .map_err(|error| {
                    Error::Api(format!(
                        "Getting keys failed: {}",
                        NetHsmApiError::from(error)
                    ))
                })?
                .entity
                .into_iter()
                .filter_map(|x| {
                    if let Ok(key) = KeyId::new(x.id.clone()) {
                        Some(key)
                    } else {
                        invalid_keys.push(x.id);
                        None
                    }
                })
                .collect::<Vec<KeyId>>();

            if !invalid_keys.is_empty() {
                return Err(crate::key::Error::InvalidKeyIds {
                    key_ids: invalid_keys,
                }
                .into());
            }

            valid_keys
        };

        Ok(valid_keys)
    }

    /// Gets the [public key of a key] on the NetHSM.
    ///
    /// Gets the [public key of a key] on the NetHSM, identified by `key_id`.
    /// The public key is returned in [X.509] Privacy-Enhanced Mail ([PEM]) format.
    ///
    /// This call requires using [`Credentials`] of a user in the
    /// [`Administrator`][`UserRole::Administrator`] or [`Operator`][`UserRole::Operator`]
    /// [role].
    ///
    /// ## Namespaces
    ///
    /// * Users in a [namespace] can only get public keys of keys in their own [namespace].
    /// * System-wide users (not in a [namespace]) can only get public keys of system-wide keys.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if getting the public key fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not that of a user in the
    ///   [`Administrator`][`UserRole::Administrator`] or [`Operator`][`UserRole::Operator`] [role]
    /// * the targeted key is a symmetric key (i.e. [`KeyType::Generic`]) and therefore can not
    ///   provide a public key
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{
    ///     Connection,
    ///     ConnectionSecurity,
    ///     Credentials,
    ///     KeyMechanism,
    ///     KeyType,
    ///     NetHsm,
    ///     Passphrase,
    /// };
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    /// // generate system-wide key with tag
    /// nethsm.generate_key(
    ///     KeyType::Curve25519,
    ///     vec![KeyMechanism::EdDsaSignature],
    ///     None,
    ///     Some("signing1".parse()?),
    ///     Some(vec!["tag1".to_string()]),
    ///     Some("label1".to_string()),
    /// )?;
    ///
    /// // get public key for a key with Key ID "signing1"
    /// println!("{:?}", nethsm.get_public_key(&"signing1".parse()?)?);
    /// # Ok(())
    /// # }
    /// ```
    /// [public key of a key]: https://docs.nitrokey.com/nethsm/operation#show-key-details
    /// [X.509]: https://en.wikipedia.org/wiki/X.509
    /// [PEM]: https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn get_public_key(&self, key_id: &KeyId) -> Result<String, Error> {
        debug!(
            "Retrieve public key of key \"{key_id}\" from the NetHSM at {} using {}",
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        Ok(
            keys_key_id_public_pem_get(&self.create_connection_config(), key_id.as_ref())
                .map_err(|error| {
                    Error::Api(format!(
                        "Getting public key failed: {}",
                        NetHsmApiError::from(error)
                    ))
                })?
                .entity,
        )
    }

    /// Adds a [tag for a key].
    ///
    /// Adds `tag` for a key, identified by `key_id`.
    ///
    /// A [tag for a key] is prerequisite to adding the same tag to a user in the
    /// [`Operator`][`UserRole::Operator`] [role] and thus granting it access to the key.
    ///
    /// This call requires using [`Credentials`] of a user in the
    /// [`Administrator`][`UserRole::Administrator`] [role].
    ///
    /// ## Namespaces
    ///
    /// * *N-Administrators* ([`Administrator`][`UserRole::Administrator`] users in a given
    ///   [namespace]) are only able to tag keys in their own [namespace].
    /// * *R-Administrators* (system-wide [`Administrator`][`UserRole::Administrator`] users) are
    ///   only able to tag system-wide keys.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if adding a tag to a key fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists
    /// * `tag` is already associated with the key
    /// * `tag` is invalid
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not that of a user in the
    ///   [`Administrator`][`UserRole::Administrator`] [role]
    /// * a key in a [namespace] is attempted to be tagged by an *R-Administrator*
    /// * a system-wide key is attempted to be tagged by an *N-Administrator*
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{
    ///     Connection,
    ///     ConnectionSecurity,
    ///     Credentials,
    ///     KeyMechanism,
    ///     KeyType,
    ///     NetHsm,
    ///     Passphrase,
    /// };
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    /// // generate system-wide key with tag
    /// nethsm.generate_key(
    ///     KeyType::Curve25519,
    ///     vec![KeyMechanism::EdDsaSignature],
    ///     None,
    ///     Some("signing1".parse()?),
    ///     Some(vec!["tag1".to_string()]),
    ///     Some("label".to_string()),
    /// )?;
    ///
    /// // add the tag "important" to a key with Key ID "signing1"
    /// nethsm.add_key_tag(&"signing1".parse()?, "important")?;
    /// # Ok(())
    /// # }
    /// ```
    /// [tag for a key]: https://docs.nitrokey.com/nethsm/operation#tags-for-keys
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn add_key_tag(&self, key_id: &KeyId, tag: &str) -> Result<(), Error> {
        debug!(
            "Add tag \"{tag}\" to key \"{key_id}\" on the NetHSM at {} using {}",
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        keys_key_id_restrictions_tags_tag_put(
            &self.create_connection_config(),
            tag,
            key_id.as_ref(),
        )
        .map_err(|error| {
            Error::Api(format!(
                "Adding tag for key failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Deletes a [tag from a key].
    ///
    /// Deletes `tag` from a key, identified by `key_id` on the NetHSM.
    ///
    /// Deleting a [tag from a key] removes access to it for any user in the
    /// [`Operator`][`UserRole::Operator`] [role], that carries the same tag.
    ///
    /// This call requires using [`Credentials`] of a user in the
    /// [`Administrator`][`UserRole::Administrator`] [role].
    ///
    /// ## Namespaces
    ///
    /// * *N-Administrators* ([`Administrator`][`UserRole::Administrator`] users in a given
    ///   [namespace]) are only able to delete tags from keys in their own [namespace].
    /// * *R-Administrators* (system-wide [`Administrator`][`UserRole::Administrator`] users) are
    ///   only able to delete tags from system-wide keys.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if adding a tag to a key fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists
    /// * `tag` is not associated with the key
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not that of a user in the
    ///   [`Administrator`][`UserRole::Administrator`] [role]
    /// * the tag for a key in a [namespace] is attempted to be removed by an *R-Administrator*
    /// * the tag for a system-wide key is attempted to be removed by an *N-Administrator*
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{
    ///     Connection,
    ///     ConnectionSecurity,
    ///     Credentials,
    ///     KeyMechanism,
    ///     KeyType,
    ///     NetHsm,
    ///     Passphrase,
    /// };
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    /// // generate system-wide key with tag
    /// nethsm.generate_key(
    ///     KeyType::Curve25519,
    ///     vec![KeyMechanism::EdDsaSignature],
    ///     None,
    ///     Some("signing1".parse()?),
    ///     Some(vec!["tag1".to_string(), "important".to_string()]),
    ///     Some("label1".to_string()),
    /// )?;
    ///
    /// // remove the tag "important" from a key with Key ID "signing1"
    /// nethsm.delete_key_tag(&"signing1".parse()?, "important")?;
    /// # Ok(())
    /// # }
    /// ```
    /// [tag from a key]: https://docs.nitrokey.com/nethsm/operation#tags-for-keys
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn delete_key_tag(&self, key_id: &KeyId, tag: &str) -> Result<(), Error> {
        debug!(
            "Delete tag \"{tag}\" from key \"{key_id}\" on the NetHSM at {} using {}",
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        keys_key_id_restrictions_tags_tag_delete(
            &self.create_connection_config(),
            tag,
            key_id.as_ref(),
        )
        .map_err(|error| {
            Error::Api(format!(
                "Deleting tag for key failed: {}",
                NetHsmApiError::from(error)
            ))
        })?;
        Ok(())
    }

    /// Imports a [certificate for a key].
    ///
    /// Imports a [certificate for a key] identified by `key_id`.
    /// Certificates up to 1 MiB in size are supported.
    /// **NOTE**: The imported bytes are not validated!
    ///
    /// This call requires using [`Credentials`] of a user in the
    /// [`Administrator`][`UserRole::Administrator`] [role].
    ///
    /// ## Namespaces
    ///
    /// * *N-Administrators* ([`Administrator`][`UserRole::Administrator`] users in a given
    ///   [namespace]) are only able to import certificates for keys in their own [namespace].
    /// * *R-Administrators* (system-wide [`Administrator`][`UserRole::Administrator`] users) are
    ///   only able to import certificates for system-wide keys.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if importing a [certificate for a key] fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists
    /// * the `data` is invalid
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not that of a user in the
    ///   [`Administrator`][`UserRole::Administrator`] [role]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{
    ///     Connection,
    ///     ConnectionSecurity,
    ///     Credentials,
    ///     KeyMechanism,
    ///     KeyType,
    ///     NetHsm,
    ///     OpenPgpKeyUsageFlags,
    ///     OpenPgpVersion,
    ///     Passphrase,
    ///     Timestamp,
    ///     UserRole,
    /// };
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    /// // add a system-wide user in the Operator role
    /// nethsm.add_user(
    ///     "Operator1".to_string(),
    ///     UserRole::Operator,
    ///     Passphrase::new("operator-passphrase".to_string()),
    ///     Some("operator1".parse()?),
    /// )?;
    /// // generate system-wide key with tag
    /// nethsm.generate_key(
    ///     KeyType::Curve25519,
    ///     vec![KeyMechanism::EdDsaSignature],
    ///     None,
    ///     Some("signing1".parse()?),
    ///     Some(vec!["tag1".to_string()]),
    ///     Some("label1".to_string()),
    /// )?;
    /// // tag system-wide user in Operator role for access to signing key
    /// nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;
    /// // use the Operator credentials to create an OpenPGP certificate for a key
    /// nethsm.use_credentials(&"operator1".parse()?)?;
    /// let openpgp_cert = nethsm.create_openpgp_cert(
    ///     &"signing1".parse()?,
    ///     OpenPgpKeyUsageFlags::default(),
    ///     &["Test <test@example.org>".parse()?],
    ///     Default::default(),
    ///     Timestamp::now(),
    ///     OpenPgpVersion::V4,
    /// )?;
    ///
    /// // use the Administrator credentials to import the OpenPGP certificate as certificate for the key
    /// nethsm.use_credentials(&"admin".parse()?)?;
    /// assert!(nethsm.get_key_certificate(&"signing1".parse()?).is_err());
    /// nethsm.import_key_certificate(&"signing1".parse()?, openpgp_cert)?;
    /// assert!(nethsm.get_key_certificate(&"signing1".parse()?).is_ok());
    /// # Ok(())
    /// # }
    /// ```
    /// [certificate for a key]: https://docs.nitrokey.com/nethsm/operation#key-certificates
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn import_key_certificate(&self, key_id: &KeyId, data: Vec<u8>) -> Result<(), Error> {
        debug!(
            "Import certificate for key \"{key_id}\" on the NetHSM at {} using {}",
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        keys_key_id_cert_put(&self.create_connection_config(), key_id.as_ref(), data).map_err(
            |error| {
                Error::Api(format!(
                    "Importing certificate for key failed: {}",
                    NetHsmApiError::from(error)
                ))
            },
        )?;
        Ok(())
    }

    /// Gets the [certificate for a key].
    ///
    /// Gets the [certificate for a key] identified by `key_id` and returns it as a byte vector.
    /// Returns [`None`] if no certificate is associated with a key identified by `key_id`.
    ///
    /// This call requires using [`Credentials`] of a user in the [`Operator`][`UserRole::Operator`]
    /// or [`Administrator`][`UserRole::Administrator`] [role].
    ///
    /// ## Namespaces
    ///
    /// * *N-Administrators* ([`Administrator`][`UserRole::Administrator`] users in a given
    ///   [namespace]) are only able to get certificates for keys in their own [namespace].
    /// * *R-Administrators* (system-wide [`Administrator`][`UserRole::Administrator`] users) are
    ///   only able to get certificates for system-wide keys.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if getting the [certificate for a key] fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not those of a user in the [`Operator`][`UserRole::Operator`]
    ///   or [`Administrator`][`UserRole::Administrator`] [role]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{
    ///     Connection,
    ///     ConnectionSecurity,
    ///     Credentials,
    ///     KeyMechanism,
    ///     KeyType,
    ///     NetHsm,
    ///     OpenPgpKeyUsageFlags,
    ///     OpenPgpVersion,
    ///     Passphrase,
    ///     Timestamp,
    ///     UserRole,
    /// };
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    /// // add a system-wide user in the Operator role
    /// nethsm.add_user(
    ///     "Operator1".to_string(),
    ///     UserRole::Operator,
    ///     Passphrase::new("operator-passphrase".to_string()),
    ///     Some("operator1".parse()?),
    /// )?;
    /// // generate system-wide key with tag
    /// nethsm.generate_key(
    ///     KeyType::Curve25519,
    ///     vec![KeyMechanism::EdDsaSignature],
    ///     None,
    ///     Some("signing1".parse()?),
    ///     Some(vec!["tag1".to_string()]),
    ///     Some("label1".to_string()),
    /// )?;
    /// // tag system-wide user in Operator role for access to signing key
    /// nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;
    /// // use the Operator credentials to create an OpenPGP certificate for a key
    /// nethsm.use_credentials(&"operator1".parse()?)?;
    /// let openpgp_cert = nethsm.create_openpgp_cert(
    ///     &"signing1".parse()?,
    ///     OpenPgpKeyUsageFlags::default(),
    ///     &["Test <test@example.org>".parse()?],
    ///     Default::default(),
    ///     Timestamp::now(),
    ///     OpenPgpVersion::V4,
    /// )?;
    /// // use the Administrator credentials to import the OpenPGP certificate as certificate for the key
    /// nethsm.use_credentials(&"admin".parse()?)?;
    /// nethsm.import_key_certificate(&"signing1".parse()?, openpgp_cert)?;
    ///
    /// // get the certificate associated with a key
    /// println!("{:?}", nethsm.get_key_certificate(&"signing1".parse()?)?);
    /// # Ok(())
    /// # }
    /// ```
    /// [certificate for a key]: https://docs.nitrokey.com/nethsm/operation#key-certificates
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn get_key_certificate(&self, key_id: &KeyId) -> Result<Option<Vec<u8>>, Error> {
        debug!(
            "Retrieve the certificate of the key \"{key_id}\" on the NetHSM at {} using {}",
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        match keys_key_id_cert_get(&self.create_connection_config(), key_id.as_ref()) {
            Ok(response) => Ok(Some(response.entity)),
            Err(nethsm_sdk_rs::apis::Error::ResponseError(error)) if error.status == 404 => {
                Ok(None)
            }
            Err(error) => Err(Error::Api(format!(
                "Getting certificate for key failed: {}",
                NetHsmApiError::from(error)
            ))),
        }
    }

    /// Deletes the [certificate for a key].
    ///
    /// Deletes the [certificate for a key] identified by `key_id`.
    ///
    /// This call requires using [`Credentials`] of a user in the
    /// [`Administrator`][`UserRole::Administrator`] [role].
    ///
    /// ## Namespaces
    ///
    /// * *N-Administrators* ([`Administrator`][`UserRole::Administrator`] users in a given
    ///   [namespace]) are only able to delete certificates for keys in their own [namespace].
    /// * *R-Administrators* (system-wide [`Administrator`][`UserRole::Administrator`] users) are
    ///   only able to delete certificates for system-wide keys.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if deleting the [certificate for a key] fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists
    /// * no certificate is associated with the key
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not that of a user in the
    ///   [`Administrator`][`UserRole::Administrator`] [role]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{
    ///     Connection,
    ///     ConnectionSecurity,
    ///     Credentials,
    ///     KeyMechanism,
    ///     KeyType,
    ///     NetHsm,
    ///     OpenPgpKeyUsageFlags,
    ///     OpenPgpVersion,
    ///     Passphrase,
    ///     Timestamp,
    ///     UserRole,
    /// };
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    /// // add a system-wide user in the Operator role
    /// nethsm.add_user(
    ///     "Operator1".to_string(),
    ///     UserRole::Operator,
    ///     Passphrase::new("operator-passphrase".to_string()),
    ///     Some("operator1".parse()?),
    /// )?;
    /// // generate system-wide key with tag
    /// nethsm.generate_key(
    ///     KeyType::Curve25519,
    ///     vec![KeyMechanism::EdDsaSignature],
    ///     None,
    ///     Some("signing1".parse()?),
    ///     Some(vec!["tag1".to_string()]),
    ///     Some("label1".to_string()),
    /// )?;
    /// // tag system-wide user in Operator role for access to signing key
    /// nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;
    /// // use the Operator credentials to create an OpenPGP certificate for a key
    /// nethsm.use_credentials(&"operator1".parse()?)?;
    /// let openpgp_cert = nethsm.create_openpgp_cert(
    ///     &"signing1".parse()?,
    ///     OpenPgpKeyUsageFlags::default(),
    ///     &["Test <test@example.org>".parse()?],
    ///     Default::default(),
    ///     Timestamp::now(),
    ///     OpenPgpVersion::V4,
    /// )?;
    /// // use the Administrator credentials to import the OpenPGP certificate as certificate for the key
    /// nethsm.use_credentials(&"admin".parse()?)?;
    /// nethsm.import_key_certificate(&"signing1".parse()?, openpgp_cert)?;
    ///
    /// // delete a certificate for a key with Key ID "signing1"
    /// assert!(nethsm.delete_key_certificate(&"signing1".parse()?).is_ok());
    /// nethsm.delete_key_certificate(&"signing1".parse()?)?;
    /// assert!(nethsm.delete_key_certificate(&"signing1".parse()?).is_err());
    /// # Ok(())
    /// # }
    /// ```
    /// [certificate for a key]: https://docs.nitrokey.com/nethsm/operation#key-certificates
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn delete_key_certificate(&self, key_id: &KeyId) -> Result<(), Error> {
        debug!(
            "Delete the certificate for the key \"{key_id}\" on the NetHSM at {} using {}",
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        keys_key_id_cert_delete(&self.create_connection_config(), key_id.as_ref()).map_err(
            |error| {
                Error::Api(format!(
                    "Deleting certificate for key failed: {}",
                    NetHsmApiError::from(error)
                ))
            },
        )?;
        Ok(())
    }

    /// Gets a [Certificate Signing Request for a key].
    ///
    /// Returns a Certificate Signing Request ([CSR]) for a key, identified by `key_id` in [PKCS#10]
    /// format based on a provided [`DistinguishedName`].
    ///
    /// This call requires using [`Credentials`] of a user in the [`Operator`][`UserRole::Operator`]
    /// or [`Administrator`][`UserRole::Administrator`] [role].
    ///
    /// ## Namespaces
    ///
    /// * Users in a [namespace] only have access to keys in their own [namespace]
    /// * System-wide users only have access to system-wide keys (not in a [namespace]).
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if getting a CSR for a key fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not those of a user in the [`Operator`][`UserRole::Operator`]
    ///   or [`Administrator`][`UserRole::Administrator`] [role]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{
    ///     Connection,
    ///     ConnectionSecurity,
    ///     Credentials,
    ///     DistinguishedName,
    ///     KeyMechanism,
    ///     KeyType,
    ///     NetHsm,
    ///     Passphrase,
    /// };
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    /// // generate system-wide key with tag
    /// nethsm.generate_key(
    ///     KeyType::Curve25519,
    ///     vec![KeyMechanism::EdDsaSignature],
    ///     None,
    ///     Some("signing1".parse()?),
    ///     Some(vec!["tag1".to_string()]),
    ///     Some("label1".to_string()),
    /// )?;
    ///
    /// // get a CSR for a key
    /// let distinguished_name = {
    ///     let mut distinguished_name = DistinguishedName::new("example.org".to_string());
    ///     distinguished_name.country_name = Some("DE".to_string());
    ///     distinguished_name.state_or_province_name = Some("Berlin".to_string());
    ///     distinguished_name.locality_name = Some("Berlin".to_string());
    ///     distinguished_name.organization_name = Some("Foobar Inc".to_string());
    ///     distinguished_name.organizational_unit_name = Some("Department of Foo".to_string());
    ///     distinguished_name.email_address = Some("foobar@mcfooface.com".to_string());
    ///     distinguished_name.subject_alt_names = Some(vec!["other.example.org".to_string()]);
    ///     distinguished_name
    /// };
    /// println!(
    ///     "{}",
    ///     nethsm.get_key_csr(&"signing1".parse()?, distinguished_name)?
    /// );
    /// # Ok(())
    /// # }
    /// ```
    /// [Certificate Signing Request for a key]: https://docs.nitrokey.com/nethsm/operation#key-certificate-signing-requests
    /// [CSR]: https://en.wikipedia.org/wiki/Certificate_signing_request
    /// [PKCS#10]: https://en.wikipedia.org/wiki/Certificate_signing_request#Structure_of_a_PKCS_#10_CSR
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn get_key_csr(
        &self,
        key_id: &KeyId,
        distinguished_name: DistinguishedName,
    ) -> Result<String, Error> {
        debug!(
            "Retrieve a Certificate Signing Request ({}) for the key \"{key_id}\" on the NetHSM at {} using {}",
            distinguished_name.common_name,
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        Ok(keys_key_id_csr_pem_post(
            &self.create_connection_config(),
            key_id.as_ref(),
            distinguished_name,
        )
        .map_err(|error| {
            Error::Api(format!(
                "Getting CSR for key failed: {}",
                NetHsmApiError::from(error)
            ))
        })?
        .entity)
    }

    /// [Signs] a digest using a key.
    ///
    /// [Signs] a `digest` using a key identified by `key_id`.
    ///
    /// **NOTE**: This function offers low-level access for signing [digests]. Use
    /// [`sign`][`NetHsm::sign`] for signing a message.
    ///
    /// The `digest` must be of appropriate type depending on `signature_type`:
    /// * [`SignatureType::Pkcs1`], [`SignatureType::PssSha256`] and [`SignatureType::EcdsaP256`]
    ///   require a [SHA-256] digest
    /// * [`SignatureType::PssSha1`] requires a [SHA-1] digest
    /// * [`SignatureType::PssSha384`] and [`SignatureType::EcdsaP384`] require a [SHA-384] digest
    /// * [`SignatureType::PssSha512`] and [`SignatureType::EcdsaP521`] require a [SHA-521] digest
    /// * [`SignatureType::EdDsa`] requires no digest (`digest` is the message)
    ///
    /// The returned data depends on the chosen [`SignatureType`]:
    ///
    /// * [`SignatureType::Pkcs1`] returns the [PKCS 1] padded signature (no signature algorithm OID
    ///   prepended, since the used hash is not known).
    /// * [`SignatureType::PssSha1`], [`SignatureType::PssSha224`], [`SignatureType::PssSha256`],
    ///   [`SignatureType::PssSha384`] and [`SignatureType::PssSha512`] return the [EMSA-PSS]
    ///   encoded signature.
    /// * [`SignatureType::EdDsa`] returns the encoding as specified in [RFC 8032 (5.1.6)] (`r`
    ///   appended with `s` (each 32 bytes), in total 64 bytes).
    /// * [`SignatureType::EcdsaP256`], [`SignatureType::EcdsaP384`] and
    ///   [`SignatureType::EcdsaP521`] return the [ASN.1] [DER] encoded signature (a sequence of
    ///   integer `r` and integer `s`).
    ///
    /// This call requires using [`Credentials`] of a user in the [`Operator`][`UserRole::Operator`]
    /// [role], which carries a tag (see [`add_user_tag`][`NetHsm::add_user_tag`]) matching one
    /// of the tags of the targeted key (see [`add_key_tag`][`NetHsm::add_key_tag`]).
    ///
    /// ## Namespaces
    ///
    /// * [`Operator`][`UserRole::Operator`] users in a [namespace] only have access to keys in
    ///   their own [namespace].
    /// * System-wide [`Operator`][`UserRole::Operator`] users only have access to system-wide keys.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if signing the `digest` fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists on the NetHSM
    /// * the chosen [`SignatureType`] is incompatible with the targeted key
    /// * the chosen `digest` is incompatible with the [`SignatureType`]
    /// * the [`Operator`][`UserRole::Operator`] user does not have access to the key (e.g.
    ///   different [namespace])
    /// * the [`Operator`][`UserRole::Operator`] user does not carry a tag matching one of the key
    ///   tags
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not that of a user in the [`Operator`][`UserRole::Operator`]
    ///   [role]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{
    ///     Connection,
    ///     ConnectionSecurity,
    ///     Credentials,
    ///     KeyMechanism,
    ///     KeyType,
    ///     NetHsm,
    ///     Passphrase,
    ///     SignatureType,
    ///     UserRole,
    /// };
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    /// // add a system-wide user in the Operator role
    /// nethsm.add_user(
    ///     "Operator1".to_string(),
    ///     UserRole::Operator,
    ///     Passphrase::new("operator-passphrase".to_string()),
    ///     Some("operator1".parse()?),
    /// )?;
    /// // generate system-wide key with tag
    /// nethsm.generate_key(
    ///     KeyType::Curve25519,
    ///     vec![KeyMechanism::EdDsaSignature],
    ///     None,
    ///     Some("signing1".parse()?),
    ///     Some(vec!["tag1".to_string()]),
    ///     Some("label1".to_string()),
    /// )?;
    /// // tag system-wide user in Operator role for access to signing key
    /// nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;
    ///
    /// // create an ed25519 signature
    /// nethsm.use_credentials(&"operator1".parse()?)?;
    /// println!(
    ///     "{:?}",
    ///     nethsm.sign_digest(&"signing1".parse()?, SignatureType::EdDsa, &[0, 1, 2])?
    /// );
    /// # Ok(())
    /// # }
    /// ```
    /// [Signs]: https://docs.nitrokey.com/nethsm/operation#sign
    /// [digests]: https://en.wikipedia.org/wiki/Cryptographic_hash_function
    /// [SHA-256]: https://en.wikipedia.org/wiki/SHA-2
    /// [MD5]: https://en.wikipedia.org/wiki/MD5
    /// [SHA-1]: https://en.wikipedia.org/wiki/SHA-1
    /// [SHA-224]: https://en.wikipedia.org/wiki/SHA-2
    /// [SHA-384]: https://en.wikipedia.org/wiki/SHA-2
    /// [SHA-521]: https://en.wikipedia.org/wiki/SHA-2
    /// [PKCS 1]: https://en.wikipedia.org/wiki/PKCS_1
    /// [EMSA-PSS]: https://en.wikipedia.org/wiki/PKCS_1
    /// [RFC 8032 (5.1.6)]: https://www.rfc-editor.org/rfc/rfc8032#section-5.1.6
    /// [ASN.1]: https://en.wikipedia.org/wiki/ASN.1
    /// [DER]: https://en.wikipedia.org/wiki/X.690#DER_encoding
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn sign_digest(
        &self,
        key_id: &KeyId,
        signature_type: SignatureType,
        digest: &[u8],
    ) -> Result<Vec<u8>, Error> {
        debug!(
            "Sign a digest (signature type: {signature_type}) with the key \"{key_id}\" on the NetHSM at {} using {}",
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        // decode base64 encoded data from the API
        Base64::decode_vec(
            &keys_key_id_sign_post(
                &self.create_connection_config(),
                key_id.as_ref(),
                SignRequestData::new(signature_type.try_into()?, Base64::encode_string(digest)),
            )
            .map_err(|error| {
                Error::Api(format!(
                    "Signing message failed: {}",
                    NetHsmApiError::from(error)
                ))
            })?
            .entity
            .signature,
        )
        .map_err(Error::Base64Decode)
    }

    /// [Signs] a message using a key.
    ///
    /// [Signs] a `message` using a key identified by `key_id` based on a specific `signature_type`.
    ///
    /// The `message` should not be [hashed], as this function takes care of it based on the
    /// provided [`SignatureType`]. For lower level access, see
    /// [`sign_digest`][`NetHsm::sign_digest`].
    ///
    /// The returned data depends on the chosen [`SignatureType`]:
    ///
    /// * [`SignatureType::Pkcs1`] returns the [PKCS 1] padded signature (no signature algorithm OID
    ///   prepended, since the used hash is not known).
    /// * [`SignatureType::PssSha1`], [`SignatureType::PssSha224`], [`SignatureType::PssSha256`],
    ///   [`SignatureType::PssSha384`] and [`SignatureType::PssSha512`] return the [EMSA-PSS]
    ///   encoded signature.
    /// * [`SignatureType::EdDsa`] returns the encoding as specified in [RFC 8032 (5.1.6)] (`r`
    ///   appended with `s` (each 32 bytes), in total 64 bytes).
    /// * [`SignatureType::EcdsaP256`], [`SignatureType::EcdsaP384`] and
    ///   [`SignatureType::EcdsaP521`] return the [ASN.1] [DER] encoded signature (a sequence of
    ///   integer `r` and integer `s`).
    ///
    /// This call requires using [`Credentials`] of a user in the [`Operator`][`UserRole::Operator`]
    /// [role], which carries a tag (see [`add_user_tag`][`NetHsm::add_user_tag`]) matching one
    /// of the tags of the targeted key (see [`add_key_tag`][`NetHsm::add_key_tag`]).
    ///
    /// ## Namespaces
    ///
    /// * [`Operator`][`UserRole::Operator`] users in a [namespace] only have access to keys in
    ///   their own [namespace].
    /// * System-wide [`Operator`][`UserRole::Operator`] users only have access to system-wide keys.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if signing the `message` fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists on the NetHSM
    /// * the chosen [`SignatureType`] is incompatible with the targeted key
    /// * the [`Operator`][`UserRole::Operator`] user does not have access to the key (e.g.
    ///   different [namespace])
    /// * the [`Operator`][`UserRole::Operator`] user does not carry a tag matching one of the key
    ///   tags
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not that of a user in the [`Operator`][`UserRole::Operator`]
    ///   [role]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{
    ///     Connection,
    ///     ConnectionSecurity,
    ///     Credentials,
    ///     KeyMechanism,
    ///     KeyType,
    ///     NetHsm,
    ///     Passphrase,
    ///     SignatureType,
    ///     UserRole,
    /// };
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    /// // add a system-wide user in the Operator role
    /// nethsm.add_user(
    ///     "Operator1".to_string(),
    ///     UserRole::Operator,
    ///     Passphrase::new("operator-passphrase".to_string()),
    ///     Some("operator1".parse()?),
    /// )?;
    /// // generate system-wide key with tag
    /// nethsm.generate_key(
    ///     KeyType::Curve25519,
    ///     vec![KeyMechanism::EdDsaSignature],
    ///     None,
    ///     Some("signing1".parse()?),
    ///     Some(vec!["tag1".to_string()]),
    ///     Some("label1".to_string()),
    /// )?;
    /// // tag system-wide user in Operator role for access to signing key
    /// nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;
    ///
    /// // create an ed25519 signature
    /// println!(
    ///     "{:?}",
    ///     nethsm.sign(&"signing1".parse()?, SignatureType::EdDsa, b"message")?
    /// );
    /// # Ok(())
    /// # }
    /// ```
    /// [Signs]: https://docs.nitrokey.com/nethsm/operation#sign
    /// [hashed]: https://en.wikipedia.org/wiki/Cryptographic_hash_function
    /// [PKCS 1]: https://en.wikipedia.org/wiki/PKCS_1
    /// [EMSA-PSS]: https://en.wikipedia.org/wiki/PKCS_1
    /// [RFC 8032 (5.1.6)]: https://www.rfc-editor.org/rfc/rfc8032#section-5.1.6
    /// [ASN.1]: https://en.wikipedia.org/wiki/ASN.1
    /// [DER]: https://en.wikipedia.org/wiki/X.690#DER_encoding
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn sign(
        &self,
        key_id: &KeyId,
        signature_type: SignatureType,
        message: &[u8],
    ) -> Result<Vec<u8>, Error> {
        debug!(
            "Sign a message (signature type: {signature_type}) with the key \"{key_id}\" on the NetHSM at {} using {}",
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        // 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
            | SignatureType::EcdsaK256 => {
                let mut hasher = Sha256::new();
                hasher.update(message);
                &hasher.finalize()[..]
            }
            SignatureType::PssSha1 => {
                let mut hasher = Sha1::new();
                hasher.update(message);
                &hasher.finalize()[..]
            }
            SignatureType::EcdsaP224 | SignatureType::PssSha224 => {
                let mut hasher = Sha224::new();
                hasher.update(message);
                &hasher.finalize()[..]
            }
            SignatureType::PssSha384 | SignatureType::EcdsaP384 => {
                let mut hasher = Sha384::new();
                hasher.update(message);
                &hasher.finalize()[..]
            }
            SignatureType::PssSha512 | SignatureType::EcdsaP521 => {
                let mut hasher = Sha512::new();
                hasher.update(message);
                &hasher.finalize()[..]
            }
            SignatureType::EdDsa => message,
        };

        self.sign_digest(key_id, signature_type, message)
    }

    /// [Encrypts] a message using a [symmetric key].
    ///
    /// [Encrypts] a `message` using a [symmetric key] identified by `key_id`, a specific
    /// [`EncryptMode`] `mode` and initialization vector `iv`.
    ///
    /// The targeted key must be of type [`KeyType::Generic`] and feature the mechanisms
    /// [`KeyMechanism::AesDecryptionCbc`] and [`KeyMechanism::AesEncryptionCbc`].
    ///
    /// This call requires using [`Credentials`] of a user in the [`Operator`][`UserRole::Operator`]
    /// [role], which carries a tag (see [`add_user_tag`][`NetHsm::add_user_tag`]) matching one
    /// of the tags of the targeted key (see [`add_key_tag`][`NetHsm::add_key_tag`]).
    ///
    /// ## Namespaces
    ///
    /// * [`Operator`][`UserRole::Operator`] users in a [namespace] only have access to keys in
    ///   their own [namespace].
    /// * System-wide [`Operator`][`UserRole::Operator`] users only have access to system-wide keys.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if encrypting the `message` fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists on the NetHSM
    /// * the chosen `mode` is incompatible with the targeted key
    /// * the [`Operator`][`UserRole::Operator`] user does not have access to the key (e.g.
    ///   different [namespace])
    /// * the [`Operator`][`UserRole::Operator`] user does not carry a tag matching one of the key
    ///   tags
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not that of a user in the [`Operator`][`UserRole::Operator`]
    ///   [role]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{
    ///     Connection,
    ///     ConnectionSecurity,
    ///     Credentials,
    ///     EncryptMode,
    ///     KeyMechanism,
    ///     KeyType,
    ///     NetHsm,
    ///     Passphrase,
    ///     UserRole,
    /// };
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    /// // add a system-wide user in the Operator role
    /// nethsm.add_user(
    ///     "Operator1".to_string(),
    ///     UserRole::Operator,
    ///     Passphrase::new("operator-passphrase".to_string()),
    ///     Some("operator1".parse()?),
    /// )?;
    /// // generate system-wide key with tag
    /// nethsm.generate_key(
    ///     KeyType::Generic,
    ///     vec![KeyMechanism::AesDecryptionCbc, KeyMechanism::AesEncryptionCbc],
    ///     Some(128),
    ///     Some("encryption1".parse()?),
    ///     Some(vec!["tag1".to_string()]),
    ///     Some("label1".to_string()),
    /// )?;
    /// // tag system-wide user in Operator role for access to signing key
    /// nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;
    ///
    /// // assuming we have an AES128 encryption key, the message must be a multiple of 32 bytes long
    /// let message = b"Hello World! This is a message!!";
    /// // we have an AES128 encryption key. the initialization vector must be a multiple of 16 bytes long
    /// let iv = b"This is unsafe!!";
    ///
    /// // encrypt message using
    /// println!(
    ///     "{:?}",
    ///     nethsm.encrypt(&"encryption1".parse()?, EncryptMode::AesCbc, message, Some(iv))?
    /// );
    /// # Ok(())
    /// # }
    /// ```
    /// [Encrypts]: https://docs.nitrokey.com/nethsm/operation#encrypt
    /// [symmetric key]: https://en.wikipedia.org/wiki/Symmetric-key_algorithm
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn encrypt(
        &self,
        key_id: &KeyId,
        mode: EncryptMode,
        message: &[u8],
        iv: Option<&[u8]>,
    ) -> Result<Vec<u8>, Error> {
        debug!(
            "Encrypt a message (encrypt mode: {mode}) with the key \"{key_id}\" on the NetHSM at {} using {}",
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        // the API requires data to be base64 encoded
        let message = Base64::encode_string(message);
        let iv = iv.map(Base64::encode_string);

        // WARNING: Upstream has decided to set all models non-exhaustive.
        //
        // On each update to nethsm-sdk-rs, check whether EncryptRequestData has gained further
        // fields.
        let encrypt_request_data = {
            let mut encrypt_request_data = EncryptRequestData::new(mode.into(), message);
            encrypt_request_data.iv = iv;
            encrypt_request_data
        };

        // decode base64 encoded data from the API
        Base64::decode_vec(
            &keys_key_id_encrypt_post(
                &self.create_connection_config(),
                key_id.as_ref(),
                encrypt_request_data,
            )
            .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] a `message` using a key identified by `key_id`, a specific [`DecryptMode`] `mode`
    /// and initialization vector `iv`.
    ///
    /// This function can be used to decrypt messages encrypted using a [symmetric key] (e.g. using
    /// [`encrypt`][`NetHsm::encrypt`]) by providing [`DecryptMode::AesCbc`] as `mode`. The targeted
    /// key must be of type [`KeyType::Generic`] and feature the mechanisms
    /// [`KeyMechanism::AesDecryptionCbc`] and [`KeyMechanism::AesEncryptionCbc`].
    ///
    /// Decryption for messages encrypted using an [asymmetric key] is also possible. Foreign
    /// entities can use the public key of an [asymmetric key] (see
    /// [`get_public_key`][`NetHsm::get_public_key`]) to encrypt a message and the private key
    /// on the NetHSM is used for decryption.
    ///
    /// This call requires using [`Credentials`] of a user in the [`Operator`][`UserRole::Operator`]
    /// [role], which carries a tag (see [`add_user_tag`][`NetHsm::add_user_tag`]) matching one
    /// of the tags of the targeted key (see [`add_key_tag`][`NetHsm::add_key_tag`]).
    ///
    /// ## Namespaces
    ///
    /// * [`Operator`][`UserRole::Operator`] users in a [namespace] only have access to keys in
    ///   their own [namespace].
    /// * System-wide [`Operator`][`UserRole::Operator`] users only have access to system-wide keys.
    ///
    /// # Errors
    ///
    /// Returns an [`Error::Api`] if decrypting the `message` fails:
    /// * the NetHSM is not in [`Operational`][`SystemState::Operational`] [state]
    /// * no key identified by `key_id` exists on the NetHSM
    /// * the chosen `mode` is incompatible with the targeted key
    /// * the encrypted message can not be decrypted
    /// * the [`Operator`][`UserRole::Operator`] user does not have access to the key (e.g.
    ///   different [namespace])
    /// * the [`Operator`][`UserRole::Operator`] user does not carry a tag matching one of the key
    ///   tags
    /// * the used [`Credentials`] are not correct
    /// * the used [`Credentials`] are not that of a user in the [`Operator`][`UserRole::Operator`]
    ///   [role]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use nethsm::{
    ///     Connection,
    ///     ConnectionSecurity,
    ///     Credentials,
    ///     DecryptMode,
    ///     EncryptMode,
    ///     KeyMechanism,
    ///     KeyType,
    ///     NetHsm,
    ///     Passphrase,
    ///     UserRole
    /// };
    /// use rand::{SeedableRng, rngs::ChaCha20Rng, rng};
    /// use rsa::{pkcs8::DecodePublicKey, Pkcs1v15Encrypt, RsaPublicKey};
    ///
    /// # fn main() -> testresult::TestResult {
    /// // create a connection with a system-wide user in the Administrator role (R-Administrator)
    /// let nethsm = NetHsm::new(
    ///     Connection::new(
    ///         "https://example.org/api/v1".try_into()?,
    ///         ConnectionSecurity::Unsafe,
    ///     ),
    ///     Some(Credentials::new(
    ///         "admin".parse()?,
    ///         Some(Passphrase::new("passphrase".to_string())),
    ///     )),
    ///     None,
    ///     None,
    /// )?;
    /// // add a system-wide user in the Operator role
    /// nethsm.add_user(
    ///     "Operator1".to_string(),
    ///     UserRole::Operator,
    ///     Passphrase::new("operator-passphrase".to_string()),
    ///     Some("operator1".parse()?),
    /// )?;
    /// // generate system-wide keys with the same tag
    /// nethsm.generate_key(
    ///     KeyType::Generic,
    ///     vec![KeyMechanism::AesDecryptionCbc, KeyMechanism::AesEncryptionCbc],
    ///     Some(128),
    ///     Some("encryption1".parse()?),
    ///     Some(vec!["tag1".to_string()]),
    ///     Some("label".to_string()),
    /// )?;
    /// nethsm.generate_key(
    ///     KeyType::Rsa,
    ///     vec![KeyMechanism::RsaDecryptionPkcs1],
    ///     None,
    ///     Some("encryption2".parse()?),
    ///     Some(vec!["tag2".to_string()]),
    ///     Some("label2".to_string()),
    /// )?;
    /// // tag system-wide user in Operator role for access to signing key
    /// nethsm.add_user_tag(&"operator1".parse()?, "tag1")?;
    ///
    /// // assuming we have an AES128 encryption key, the message must be a multiple of 32 bytes long
    /// let message = "Hello World! This is a message!!".to_string();
    /// // we have an AES128 encryption key. the initialization vector must be a multiple of 16 bytes long
    /// let iv = "This is unsafe!!".to_string();
    ///
    /// // encrypt message using a symmetric key
    /// nethsm.use_credentials(&"operator1".parse()?)?;
    /// let encrypted_message = nethsm.encrypt(&"encryption1".parse()?, EncryptMode::AesCbc, message.as_bytes(), Some(iv.as_bytes()))?;
    ///
    /// // decrypt message using the same symmetric key and the same initialization vector
    /// assert_eq!(
    ///     message.as_bytes(),
    ///     &nethsm.decrypt(&"encryption1".parse()?, DecryptMode::AesCbc, &encrypted_message, Some(iv.as_bytes()))?
    /// );
    ///
    /// // get the public key of an asymmetric key and encrypt the message with it
    /// let pubkey = RsaPublicKey::from_public_key_pem(&nethsm.get_public_key(&"encryption2".parse()?)?)?;
    /// let encrypted_message = pubkey.encrypt(&mut ChaCha20Rng::from_rng(&mut rng()), Pkcs1v15Encrypt, message.as_bytes())?;
    /// println!("raw encrypted message: {:?}", encrypted_message);
    ///
    /// let decrypted_message =
    ///     nethsm.decrypt(&"encryption2".parse()?, DecryptMode::Pkcs1, &encrypted_message, None)?;
    /// println!("raw decrypted message: {:?}", decrypted_message);
    ///
    /// assert_eq!(&decrypted_message, message.as_bytes());
    /// # Ok(())
    /// # }
    /// ```
    /// [Decrypts]: https://docs.nitrokey.com/nethsm/operation#decrypt
    /// [symmetric key]: https://en.wikipedia.org/wiki/Symmetric-key_algorithm
    /// [asymmetric key]: https://en.wikipedia.org/wiki/Public-key_cryptography
    /// [namespace]: https://docs.nitrokey.com/nethsm/administration#namespaces
    /// [role]: https://docs.nitrokey.com/nethsm/administration#roles
    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
    pub fn decrypt(
        &self,
        key_id: &KeyId,
        mode: DecryptMode,
        message: &[u8],
        iv: Option<&[u8]>,
    ) -> Result<Vec<u8>, Error> {
        debug!(
            "Decrypt a message (decrypt mode: {mode}; IV: {}) with the key \"{key_id}\" on the NetHSM at {} using {}",
            if iv.is_some() { "yes" } else { "no" },
            self.url.borrow(),
            user_or_no_user_string(self.current_credentials.borrow().as_ref()),
        );

        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
        // the API requires data to be base64 encoded
        let encrypted = Base64::encode_string(message);
        let iv = iv.map(Base64::encode_string);

        // WARNING: Upstream has decided to set all models non-exhaustive.
        //
        // On each update to nethsm-sdk-rs, check whether EncryptRequestData has gained further
        // fields.
        let decrypt_request_data = {
            let mut decrypt_request_data = DecryptRequestData::new(mode.into(), encrypted);
            decrypt_request_data.iv = iv;
            decrypt_request_data
        };

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