signstar_yubihsm2/

signer.rs

//! Signing data with YubiHSM.

use signstar_crypto::{
    Error as SignstarCryptoError,
    signer::{
        error::Error as SignstarCryptoSignerError,
        traits::{RawPublicKey, RawSigningKey},
    },
};
use yubihsm::{
    Connector,
    HttpConfig,
    UsbConfig,
    asymmetric::Algorithm,
    client::Client,
    device::SerialNumber,
    object::Id,
};

use crate::{
    Credentials,
    Error,
    connection::{DEFAULT_HTTP_TIMEOUT_MILLIS, YubiHsmUrl},
};

/// A signing key stored in the YubiHSM.
pub struct YubiHsm2SigningKey {
    yubihsm: Client,
    key_id: Id,
}

impl YubiHsm2SigningKey {
    /// Creates a new [`YubiHsm2SigningKey`] for a [`Client`] and the [`Id`] of a signing key.
    pub fn new(client: Client, id: Id) -> Self {
        Self {
            yubihsm: client,
            key_id: id,
        }
    }

    /// Returns the reference for the inner client instance.
    pub fn client(&self) -> &Client {
        &self.yubihsm
    }

    /// Closes the session for the [`YubiHsm2SigningKey`]'s [`Client`].
    ///
    /// # Errors
    ///
    /// Returns an error if [`Client::close_session`] fails.
    pub fn close_session(&self) -> Result<(), crate::Error> {
        self.yubihsm
            .close_session()
            .map_err(|source| crate::Error::Client {
                context: "closing the session for a YubiHSM signing key implementation",
                source,
            })
    }

    /// Returns a signing key emulated in software.
    ///
    /// # Warning
    ///
    /// The signing key created by this function should be used only for tests as the signing
    /// material is exposed in memory!
    ///
    /// # Errors
    ///
    /// When automatic provisioning of the emulator fails this function can return [`Error`].
    ///
    /// # Panics
    ///
    /// This function panics if certificate generation fails.
    #[cfg(feature = "_yubihsm2-mockhsm")]
    pub fn mock(key_id: Id, credentials: &Credentials) -> Result<Self, Error> {
        use signstar_crypto::traits::UserWithPassphrase as _;
        use yubihsm::{Credentials as YubiCredentials, authentication};

        use crate::mock::setup_single_key_in_mockhsm;

        let connector = setup_single_key_in_mockhsm(key_id, credentials)?;

        let auth_key = authentication::Key::derive_from_password(
            credentials.passphrase().expose_borrowed().as_bytes(),
        );
        let client = Client::open(
            connector,
            YubiCredentials::new(credentials.id(), auth_key),
            true,
        )
        .map_err(|source| Error::Client {
            context: "connecting to mockhsm",
            source,
        })?;
        Ok(Self::new(client, key_id))
    }

    /// Returns a new [`YubiHsm2SigningKey`] backed by a remote YubiHSM2.
    ///
    /// The target device is identified by the URL.
    ///
    /// # Errors
    ///
    /// Returns an error, if creating a client connection to the backend fails.
    pub fn new_remote(
        url: YubiHsmUrl,
        key_id: Id,
        credentials: &Credentials,
    ) -> Result<Self, Error> {
        let connector = Connector::http(&HttpConfig {
            addr: url.host().into(),
            port: url.port(),
            tls: url.scheme() == "https",
            timeout_ms: DEFAULT_HTTP_TIMEOUT_MILLIS,
        });
        let client =
            Client::open(connector, credentials.into(), true).map_err(|source| Error::Client {
                context: "connecting to a hardware device",
                source,
            })?;
        Ok(Self {
            yubihsm: client,
            key_id,
        })
    }

    /// Returns a new [`YubiHsm2SigningKey`] backed by specific YubiHSM2 hardware.
    ///
    /// The hardware is identified using its `serial_number` and the key is addressed by its
    /// `key_id`.
    ///
    /// # Errors
    ///
    /// If the communication with the device fails or the authentication data is incorrect this
    /// function will return an [`Error`].
    pub fn new_with_serial_number(
        serial_number: SerialNumber,
        key_id: Id,
        credentials: &Credentials,
    ) -> Result<Self, Error> {
        let connector = Connector::usb(&UsbConfig {
            serial: Some(serial_number),
            timeout_ms: UsbConfig::DEFAULT_TIMEOUT_MILLIS,
        });
        let client =
            Client::open(connector, credentials.into(), true).map_err(|source| Error::Client {
                context: "connecting to a hardware device",
                source,
            })?;
        Ok(Self {
            yubihsm: client,
            key_id,
        })
    }
}

impl std::fmt::Debug for YubiHsm2SigningKey {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("YubiHsm2SigningKey")
            .field("key_id", &self.key_id)
            .finish()
    }
}

impl RawSigningKey for YubiHsm2SigningKey {
    /// Returns the internal key identifier formatted as a [`String`].
    fn key_id(&self) -> String {
        self.key_id.to_string()
    }

    /// Signs a raw digest.
    ///
    /// The digest is without any framing and the result will be a vector of raw signature parts.
    ///
    /// # Errors
    ///
    /// If the operation fails the implementation returns a
    /// [`signstar_crypto::signer::error::Error::Hsm`], which wraps the client-specific HSM error
    /// in its `source` field.
    fn sign(&self, digest: &[u8]) -> Result<Vec<Vec<u8>>, SignstarCryptoError> {
        let sig = self
            .yubihsm
            .sign_ed25519(self.key_id, digest)
            .map_err(|e| SignstarCryptoSignerError::Hsm {
                context: "calling yubihsm::sign_ed25519",
                source: Box::new(e),
            })?;

        Ok(vec![sig.r_bytes().into(), sig.s_bytes().into()])
    }

    /// Returns certificate bytes associated with this signing key, if any.
    ///
    /// This interface does not interpret the certificate in any way but has a notion of certificate
    /// being set or unset.
    ///
    /// # Errors
    ///
    /// If the operation fails the implementation returns a
    /// [`SignstarCryptoSignerError::Hsm`], which wraps the client-specific HSM error
    /// in its `source` field.
    fn certificate(&self) -> Result<Option<Vec<u8>>, SignstarCryptoError> {
        Ok(Some(self.yubihsm.get_opaque(self.key_id).map_err(|e| {
            SignstarCryptoSignerError::Hsm {
                context: "retrieving the certificate for a signing key held in a YubiHSM2",
                source: Box::new(e),
            }
        })?))
    }

    /// Returns raw public parts of this signing key.
    ///
    /// Implementation of this trait implies that the signing key exists and as such always has
    /// public parts. The public key is used for generating application-specific certificates.
    ///
    /// # Errors
    ///
    /// If the operation fails the implementation returns a
    /// [`SignstarCryptoSignerError::Hsm`], which wraps the client-specific HSM error
    /// in its `source` field.
    fn public(&self) -> Result<RawPublicKey, SignstarCryptoError> {
        let pk = self.yubihsm.get_public_key(self.key_id).map_err(|e| {
            SignstarCryptoSignerError::Hsm {
                context: "retrieving the public key for a signing key held in a YubiHSM2",
                source: Box::new(e),
            }
        })?;
        if pk.algorithm != Algorithm::Ed25519 {
            return Err(SignstarCryptoSignerError::InvalidPublicKeyData {
                context: format!("algorithm of the HSM key {:?} is unsupported", pk.algorithm),
            }
            .into());
        }
        Ok(RawPublicKey::Ed25519(pk.bytes))
    }
}