krypteia-quantica 0.1.0

//! SLH-DSA: Stateless Hash-Based Digital Signature Standard (FIPS 205).
//!
//! This crate provides a pure-Rust implementation of SLH-DSA (formerly known as SPHINCS+),
//! a post-quantum digital signature scheme standardized in [FIPS 205]. SLH-DSA is purely
//! hash-based: its security relies only on the properties of cryptographic hash functions,
//! with no algebraic structure (lattices, codes, etc.) that could be exploited by quantum
//! or classical algorithms beyond generic attacks.
//!
//! # Architecture
//!
//! SLH-DSA is built from a hierarchy of hash-based primitives:
//!
//! 1. **WOTS+** -- A one-time signature scheme that signs a single n-byte message using
//!    hash chains (see [`wots`]).
//! 2. **XMSS** -- An eXtended Merkle Signature Scheme that authenticates 2^h' WOTS+ keys
//!    via a binary Merkle tree, producing a few-time signature (see [`xmss`]).
//! 3. **Hypertree** -- A tree of XMSS trees stacked in `d` layers, giving a many-time
//!    signature scheme with a total tree height of `h = d * h'` (see [`hypertree`]).
//! 4. **FORS** -- A Forest of Random Subsets, a few-time signature used to sign the
//!    message digest before passing it to the hypertree (see [`fors`]).
//! 5. **SLH-DSA** -- The top-level scheme that combines FORS + Hypertree to produce a
//!    stateless, many-time signature (see [`slh`]).
//!
//! # Supported parameter sets
//!
//! This crate implements all six SHAKE-based parameter sets defined in FIPS 205 Section 11:
//!
//! | Type | 128-bit | 192-bit | 256-bit |
//! |------|---------|---------|---------|
//! | Small (s) | [`Shake128s`] | [`Shake192s`] | [`Shake256s`] |
//! | Fast (f)  | [`Shake128f`] | [`Shake192f`] | [`Shake256f`] |
//!
//! The "s" variants produce smaller signatures; the "f" variants are faster to sign and verify.
//!
//! # Examples
//!
//! ```rust
//! use quantica::slh_dsa::{SlhDsa, Shake128f, OsRng};
//!
//! // Generate a key pair
//! let mut rng = OsRng;
//! let (secret_key, public_key) = SlhDsa::<Shake128f>::keygen(&mut rng).unwrap();
//!
//! // Sign a message
//! let message = b"hello, post-quantum world!";
//! let signature = SlhDsa::<Shake128f>::sign(message, &secret_key, &mut rng).unwrap();
//!
//! // Verify the signature
//! let valid = SlhDsa::<Shake128f>::verify(message, &signature, &public_key).unwrap();
//! assert!(valid);
//! ```
//!
//! [FIPS 205]: https://doi.org/10.6028/NIST.FIPS.205

/// Address structure used to domain-separate hash calls throughout SLH-DSA.
pub mod address;
/// FORS: Forest of Random Subsets few-time signature scheme.
pub mod fors;
/// SHAKE-based tweakable hash function wrappers (H_msg, PRF, PRF_msg, T_l, H, F).
pub mod hash;
/// Hypertree: a d-layer tree of XMSS trees for many-time signing.
pub mod hypertree;
/// SLH-DSA parameter set definitions and the [`Params`] trait.
pub mod params;
/// Minimal cryptographic RNG trait and OS-backed implementation.
pub mod rng;
/// `Keccak-f[1600]` based SHAKE256 implementation (FIPS 202).
pub mod sha3;
/// Top-level SLH-DSA key generation, signing, and verification algorithms.
pub mod slh;
/// WOTS+ one-time signature scheme based on hash chains.
pub mod wots;
/// XMSS: eXtended Merkle Signature Scheme combining WOTS+ with a Merkle tree.
pub mod xmss;

// Re-export parameter set types for convenience.
pub use params::{Params, Shake128f, Shake128s, Shake192f, Shake192s, Shake256f, Shake256s};
pub use rng::CryptoRng;
#[cfg(feature = "std")]
pub use rng::OsRng;

/// Errors that can occur in SLH-DSA operations.
///
/// These errors cover failures in random number generation, malformed keys or signatures,
/// and verification mismatches. All variants are non-recoverable in the sense that retrying
/// with the same inputs will produce the same error.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SlhDsaError {
    /// The cryptographic random number generator failed to produce bytes.
    ///
    /// This typically indicates an OS-level failure (e.g., `/dev/urandom` unavailable).
    RngFailure,
    /// The provided key has an invalid format or unexpected length.
    ///
    /// Public keys must be `2*n` bytes and secret keys `4*n` bytes, where `n` is the
    /// security parameter ([`Params::N`]).
    InvalidKey,
    /// The provided signature has an invalid format or unexpected length.
    ///
    /// Signatures must be exactly [`SlhDsa::signature_size`] bytes for the chosen parameter set.
    InvalidSignature,
    /// The signature did not verify against the given message and public key.
    VerificationFailed,
    /// Signing-side fault redundancy detected a mismatch between the two
    /// independent signing runs (item `T1-C` of the SLH-DSA SCA roadmap).
    ///
    /// Gated by the `sca-fors-redundancy` cargo feature, the signer
    /// produces the FORS signature twice and aborts before emission if
    /// the two results disagree — single-fault grafting-tree forgeries
    /// (Castelnovi 2018, Adiletta 2025) cannot then propagate out of
    /// the device. The error is non-recoverable; a retry on the same
    /// inputs will either succeed (the fault was transient) or surface
    /// the same error again.
    FaultDetected,
}

impl core::fmt::Display for SlhDsaError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            SlhDsaError::RngFailure => write!(f, "RNG failure"),
            SlhDsaError::InvalidKey => write!(f, "Invalid key"),
            SlhDsaError::InvalidSignature => write!(f, "Invalid signature"),
            SlhDsaError::VerificationFailed => write!(f, "Verification failed"),
            SlhDsaError::FaultDetected => write!(f, "Signing-side fault detected by FORS redundancy"),
        }
    }
}

#[cfg(feature = "std")]
impl std::error::Error for SlhDsaError {}

use crate::secret::SecretBytes;
/// High-level SLH-DSA API parameterized by a parameter set.
///
/// This is the main entry point for using SLH-DSA. The type parameter `P` selects one of
/// the six SHAKE-based parameter sets (e.g., [`Shake128f`], [`Shake256s`]).
///
/// `SlhDsa` is a zero-sized type that serves as a namespace for the static methods
/// [`keygen`](Self::keygen), [`sign`](Self::sign), and [`verify`](Self::verify).
///
/// # Examples
///
/// ```rust
/// use quantica::slh_dsa::{SlhDsa, Shake256s, OsRng};
///
/// let mut rng = OsRng;
/// let (sk, pk) = SlhDsa::<Shake256s>::keygen(&mut rng).unwrap();
/// let sig = SlhDsa::<Shake256s>::sign(b"data", &sk, &mut rng).unwrap();
/// assert!(SlhDsa::<Shake256s>::verify(b"data", &sig, &pk).unwrap());
/// ```
use alloc::vec::Vec;
use core::marker::PhantomData;

// =====================================================================
// Typed key / signature wrappers
// =====================================================================

/// SLH-DSA **verifying key** (public key, `2 * P::N` bytes).
///
/// Type-tagged with `P`. No zeroization.
pub struct VerifyingKey<P: Params> {
    bytes: Vec<u8>,
    _marker: PhantomData<P>,
}

impl<P: Params> VerifyingKey<P> {
    /// Wrap a raw byte slice. Length is validated against
    /// [`Params::PK_LEN`].
    pub fn from_bytes(bytes: &[u8]) -> Result<Self, SlhDsaError> {
        if bytes.len() != P::PK_LEN {
            return Err(SlhDsaError::InvalidKey);
        }
        Ok(Self {
            bytes: bytes.to_vec(),
            _marker: PhantomData,
        })
    }

    /// Borrow the encoded verifying key as a byte slice.
    pub fn as_bytes(&self) -> &[u8] {
        &self.bytes
    }

    /// Length in bytes (always [`Params::PK_LEN`]).
    pub fn len(&self) -> usize {
        self.bytes.len()
    }
}

impl<P: Params> AsRef<[u8]> for VerifyingKey<P> {
    fn as_ref(&self) -> &[u8] {
        &self.bytes
    }
}

impl<P: Params> core::ops::Deref for VerifyingKey<P> {
    type Target = [u8];
    fn deref(&self) -> &[u8] {
        &self.bytes
    }
}

impl<P: Params> Clone for VerifyingKey<P> {
    fn clone(&self) -> Self {
        Self {
            bytes: self.bytes.clone(),
            _marker: PhantomData,
        }
    }
}

/// SLH-DSA **signing key** (secret key, `4 * P::N` bytes).
///
/// Backed by [`SecretBytes`] — wipes its memory on [`Drop`] via
/// `silentops::ct_zeroize`. Type-tagged with `P`.
pub struct SigningKey<P: Params> {
    bytes: SecretBytes,
    _marker: PhantomData<P>,
}

impl<P: Params> SigningKey<P> {
    /// Wrap a raw byte slice. Length is validated against
    /// [`Params::SK_LEN`].
    pub fn from_bytes(bytes: &[u8]) -> Result<Self, SlhDsaError> {
        if bytes.len() != P::SK_LEN {
            return Err(SlhDsaError::InvalidKey);
        }
        Ok(Self {
            bytes: SecretBytes::from_slice(bytes),
            _marker: PhantomData,
        })
    }

    /// Borrow the encoded signing key as a byte slice.
    pub fn as_bytes(&self) -> &[u8] {
        self.bytes.as_bytes()
    }

    /// Length in bytes (always [`Params::SK_LEN`]).
    pub fn len(&self) -> usize {
        self.bytes.len()
    }
}

impl<P: Params> AsRef<[u8]> for SigningKey<P> {
    fn as_ref(&self) -> &[u8] {
        self.bytes.as_bytes()
    }
}

impl<P: Params> core::ops::Deref for SigningKey<P> {
    type Target = [u8];
    fn deref(&self) -> &[u8] {
        self.bytes.as_bytes()
    }
}

/// SLH-DSA **signature**. Type-tagged with `P`.
///
/// Public material — not zeroized.
pub struct Signature<P: Params> {
    bytes: Vec<u8>,
    _marker: PhantomData<P>,
}

impl<P: Params> Signature<P> {
    /// Wrap a raw byte slice. Length is validated against
    /// [`params::sig_len::<P>()`].
    pub fn from_bytes(bytes: &[u8]) -> Result<Self, SlhDsaError> {
        if bytes.len() != params::sig_len::<P>() {
            return Err(SlhDsaError::InvalidSignature);
        }
        Ok(Self {
            bytes: bytes.to_vec(),
            _marker: PhantomData,
        })
    }

    /// Borrow the encoded signature as a byte slice.
    pub fn as_bytes(&self) -> &[u8] {
        &self.bytes
    }

    /// Length in bytes (always [`params::sig_len::<P>()`]).
    pub fn len(&self) -> usize {
        self.bytes.len()
    }
}

impl<P: Params> AsRef<[u8]> for Signature<P> {
    fn as_ref(&self) -> &[u8] {
        &self.bytes
    }
}

impl<P: Params> core::ops::Deref for Signature<P> {
    type Target = [u8];
    fn deref(&self) -> &[u8] {
        &self.bytes
    }
}

impl<P: Params> Clone for Signature<P> {
    fn clone(&self) -> Self {
        Self {
            bytes: self.bytes.clone(),
            _marker: PhantomData,
        }
    }
}

pub struct SlhDsa<P: Params> {
    _marker: core::marker::PhantomData<P>,
}

impl<P: Params> SlhDsa<P> {
    /// Generate a new SLH-DSA key pair using the provided RNG.
    ///
    /// Returns `(secret_key, public_key)` as byte vectors. The secret key is `4*n` bytes
    /// and the public key is `2*n` bytes, where `n = P::N`.
    ///
    /// Implements Algorithm 21 of FIPS 205.
    pub fn keygen(rng: &mut dyn CryptoRng) -> Result<(SigningKey<P>, VerifyingKey<P>), SlhDsaError> {
        let (sk_v, pk_v) = slh::slh_keygen::<P>(rng)?;
        Ok((
            SigningKey {
                bytes: SecretBytes::from_vec(sk_v),
                _marker: PhantomData,
            },
            VerifyingKey {
                bytes: pk_v,
                _marker: PhantomData,
            },
        ))
    }

    /// Generate a key pair deterministically from explicit seed material.
    ///
    /// This is the internal/deterministic variant (Algorithm 18 of FIPS 205). Each of
    /// `sk_seed`, `sk_prf`, and `pk_seed` must be exactly `P::N` bytes.
    ///
    /// Returns `(secret_key, public_key)`.
    pub fn keygen_internal(sk_seed: &[u8], sk_prf: &[u8], pk_seed: &[u8]) -> (Vec<u8>, Vec<u8>) {
        slh::slh_keygen_internal::<P>(sk_seed, sk_prf, pk_seed)
    }

    /// Sign a message using randomized (hedged) signing.
    ///
    /// Produces a signature over `message` using the given `secret_key` and fresh randomness
    /// from `rng`. The randomness provides hedged signing: even if the RNG is weak, security
    /// degrades gracefully.
    ///
    /// Implements Algorithm 22 of FIPS 205.
    pub fn sign(
        message: &[u8],
        secret_key: &SigningKey<P>,
        rng: &mut dyn CryptoRng,
    ) -> Result<Signature<P>, SlhDsaError> {
        let sig_v = slh::slh_sign::<P>(message, secret_key.as_bytes(), rng)?;
        Ok(Signature {
            bytes: sig_v,
            _marker: PhantomData,
        })
    }

    /// Sign a message with explicit additional randomness (internal variant).
    ///
    /// This is Algorithm 19 of FIPS 205. The `addrnd` parameter is `P::N` bytes of
    /// optional randomness; passing `pk_seed` here yields deterministic signing.
    ///
    /// Without the `sca-fors-redundancy` feature this is always [`Ok`]. With it,
    /// the T1-C FORS recompute-and-compare check can return
    /// [`Err(SlhDsaError::FaultDetected)`][SlhDsaError].
    pub fn sign_internal(message: &[u8], secret_key: &[u8], addrnd: &[u8]) -> Result<Vec<u8>, SlhDsaError> {
        slh::slh_sign_internal::<P>(message, secret_key, addrnd)
    }

    /// Verify a signature on a message against a public key.
    ///
    /// Returns `Ok(true)` if the signature is valid, `Ok(false)` if the signature is
    /// well-formed but does not verify, or an `Err` if the key or signature has an
    /// invalid length.
    ///
    /// Implements Algorithm 24 of FIPS 205.
    pub fn verify(message: &[u8], signature: &Signature<P>, public_key: &VerifyingKey<P>) -> Result<bool, SlhDsaError> {
        slh::slh_verify::<P>(message, signature.as_bytes(), public_key.as_bytes())
    }

    /// Returns the expected signature size in bytes for this parameter set.
    ///
    /// The signature consists of a randomizer `R` (n bytes), a FORS signature, and a
    /// hypertree signature: `n + k*(1+a)*n + (h + d*len)*n`.
    pub fn signature_size() -> usize {
        params::sig_len::<P>()
    }

    /// Returns the expected public key size in bytes (`2*n`).
    pub fn public_key_size() -> usize {
        P::PK_LEN
    }

    /// Returns the expected secret key size in bytes (`4*n`).
    pub fn secret_key_size() -> usize {
        P::SK_LEN
    }
}