footing 0.6.4

Feature-gated foundations for Rust backend services
Documentation
use std::fmt;

use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
use hmac::{Hmac, KeyInit, Mac};
use sha2::Sha256;
use zeroize::Zeroizing;

pub(crate) const MIN_SIGNING_KEY_BYTES: usize = 32;

type HmacSha256 = Hmac<Sha256>;

#[derive(Debug)]
pub(crate) struct SigningError;

/// Shared key rotation and HMAC-SHA256 signing with codec-specific framing.
#[derive(Clone)]
pub(crate) struct SigningKeys {
    active: Zeroizing<Vec<u8>>,
    previous: Vec<Zeroizing<Vec<u8>>>,
}

impl SigningKeys {
    pub(crate) fn new(key: impl AsRef<[u8]>) -> Result<Self, SigningError> {
        Ok(Self {
            active: validate_key(key)?,
            previous: Vec::new(),
        })
    }

    pub(crate) fn add_previous(&mut self, key: impl AsRef<[u8]>) -> Result<(), SigningError> {
        self.previous.push(validate_key(key)?);
        Ok(())
    }

    pub(crate) fn sign(&self, parts: &[&[u8]]) -> Result<String, SigningError> {
        let mut mac = HmacSha256::new_from_slice(&self.active).map_err(|_| SigningError)?;
        for part in parts {
            mac.update(part);
        }
        Ok(URL_SAFE_NO_PAD.encode(mac.finalize().into_bytes()))
    }

    pub(crate) fn verify(&self, parts: &[&[u8]], signature: &str) -> Result<(), SigningError> {
        let expected = URL_SAFE_NO_PAD
            .decode(signature)
            .map_err(|_| SigningError)?;
        for key in std::iter::once(&self.active).chain(&self.previous) {
            let mut mac = HmacSha256::new_from_slice(key).map_err(|_| SigningError)?;
            for part in parts {
                mac.update(part);
            }
            if mac.verify_slice(&expected).is_ok() {
                return Ok(());
            }
        }
        Err(SigningError)
    }
}

impl fmt::Debug for SigningKeys {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("SigningKeys")
            .field(
                "active_key",
                &format_args!("<redacted:{} bytes>", self.active.len()),
            )
            .field("previous_key_count", &self.previous.len())
            .finish()
    }
}

fn validate_key(key: impl AsRef<[u8]>) -> Result<Zeroizing<Vec<u8>>, SigningError> {
    let key = key.as_ref();
    if key.len() < MIN_SIGNING_KEY_BYTES {
        return Err(SigningError);
    }
    Ok(Zeroizing::new(key.to_vec()))
}