krypteia-quantica 0.2.0

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Cédric Mesnil <cslashm@pm.me>

// The key / signature / ciphertext types are fixed-size byte containers;
// `len()` returns a compile-time constant (`Params::*_LEN`), so `is_empty()`
// (always `false`) carries no meaning. Documented allow per CLAUDE.md §6.
#![allow(clippy::len_without_is_empty)]

//! 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`, internal).
//! 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`, internal).
//! 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`, internal).
//! 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`, internal).
//! 5. **SLH-DSA** -- The top-level scheme that combines FORS + Hypertree to produce a
//!    stateless, many-time signature (see `slh`, internal).
//!
//! # 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 (empty context string)
//! let message = b"hello, post-quantum world!";
//! let signature = SlhDsa::<Shake128f>::sign(message, b"", &secret_key, &mut rng).unwrap();
//!
//! // Verify the signature
//! let valid = SlhDsa::<Shake128f>::verify(message, b"", &signature, &public_key).unwrap();
//! assert!(valid);
//! ```
//!
//! [FIPS 205]: https://doi.org/10.6028/NIST.FIPS.205

// API tiers: `params`/`rng` are facade; `address`/`hash`/`hash_sha2` are
// hazmat expert bricks (no stability promise); the signature components
// (WOTS+/XMSS/FORS/hypertree) are crate-internal — they are ONE-TIME /
// few-time primitives whose standalone misuse (key reuse) enables forgery.

/// Address structure used to domain-separate hash calls throughout SLH-DSA.
#[cfg(feature = "hazmat")]
pub mod address;
#[cfg(not(feature = "hazmat"))]
pub(crate) mod address;
// FORS few-time signature component — crate-internal (misuse hazard).
pub(crate) mod fors;
/// Tweakable hash functions (H_msg, PRF, PRF_msg, T_l, H, F) and the
/// SHAKE instantiation (FIPS 205 §11.1).
#[cfg(feature = "hazmat")]
pub mod hash;
#[cfg(not(feature = "hazmat"))]
pub(crate) mod hash;
/// SHA-2 instantiation of the tweakable hash functions (FIPS 205 §11.2).
#[cfg(feature = "hazmat")]
pub mod hash_sha2;
#[cfg(not(feature = "hazmat"))]
pub(crate) mod hash_sha2;
// Hypertree composition layer — crate-internal.
pub(crate) 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;
// SHAKE256 wrappers over the shared tessera core — crate-internal.
pub(crate) mod sha3;
/// Top-level SLH-DSA algorithms — the un-typed raw-slice facade (hazmat
/// tier: no typed-wrapper validation; used by the C FFI and KAT tooling).
#[cfg(feature = "hazmat")]
pub mod slh;
#[cfg(not(feature = "hazmat"))]
pub(crate) mod slh;
// WOTS+ ONE-TIME signature component — key reuse on two messages enables
// forgery; crate-internal.
pub(crate) mod wots;
// XMSS few-time component — crate-internal.
pub(crate) mod xmss;

// In-crate KATs for the `pub(crate)` internal interface (sign/verify_internal).
#[cfg(test)]
mod acvp_internal;

// Re-export parameter set types for convenience.
pub use crate::prehash::PreHash;
pub use params::{
    Params, Sha2_128f, Sha2_128s, Sha2_192f, Sha2_192s, Sha2_256f, Sha2_256s, 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,
    /// The context string exceeds the 255-byte maximum (FIPS 205 §10.2).
    ContextTooLong,
    /// 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::ContextTooLong => write!(f, "Context string exceeds 255 bytes"),
            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", b"", &sk, &mut rng).unwrap();
/// assert!(SlhDsa::<Shake256s>::verify(b"data", b"", &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,
        }
    }
}

/// Generic SLH-DSA interface parameterized by parameter set (FIPS 205).
///
/// This struct provides the high-level API for SLH-DSA key generation,
/// signing, and verification. The type parameter `P` selects one of the
/// twelve FIPS 205 parameter sets (`Sha2_128s` … `Shake256f`) defined in
/// the `params` module.
///
/// All methods are stateless; `SlhDsa` carries no runtime data and exists
/// only to bind the parameter set at the type level.
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.
    ///
    /// Implements Algorithm 21 of FIPS 205.
    ///
    /// # Arguments
    ///
    /// * `rng` - A cryptographic random number generator implementing [`CryptoRng`].
    ///
    /// # Returns
    ///
    /// A tuple `(secret_key, public_key)` of typed wrappers. The secret key is
    /// `4*n` bytes and the public key is `2*n` bytes, where `n = P::N`.
    ///
    /// # Errors
    ///
    /// * [`SlhDsaError::RngFailure`] if the RNG cannot provide bytes.
    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,
            },
        ))
    }

    /// Sign a message with an optional context string (hedged mode).
    ///
    /// Implements Algorithm 22 of FIPS 205 (external SLH-DSA.Sign): wraps
    /// the message as `M' = 0x00 || len(ctx) || ctx || message` for domain
    /// separation, then hedged-signs it. Use an empty `ctx` (`b""`) when no
    /// context is needed — the wrapping still applies, keeping signatures
    /// interoperable with conformant verifiers.
    ///
    /// # Arguments
    ///
    /// * `message` - The message to sign (arbitrary length).
    /// * `ctx` - Optional context string, at most 255 bytes (`b""` for none).
    /// * `secret_key` - The signing key for this parameter set.
    /// * `rng` - A cryptographic random number generator implementing [`CryptoRng`].
    ///
    /// # Returns
    ///
    /// A [`Signature<P>`] of length [`SlhDsa::signature_size`].
    ///
    /// # Errors
    ///
    /// * [`SlhDsaError::ContextTooLong`] if `ctx` exceeds 255 bytes.
    /// * [`SlhDsaError::RngFailure`] if the RNG cannot provide bytes.
    /// * [`SlhDsaError::FaultDetected`] if the `sca-fors-redundancy` feature is
    ///   enabled and the two independent signing runs disagree.
    pub fn sign(
        message: &[u8],
        ctx: &[u8],
        secret_key: &SigningKey<P>,
        rng: &mut dyn CryptoRng,
    ) -> Result<Signature<P>, SlhDsaError> {
        let sig_v = slh::slh_sign::<P>(message, ctx, secret_key.as_bytes(), rng)?;
        Ok(Signature {
            bytes: sig_v,
            _marker: PhantomData,
        })
    }

    /// Sign with pre-hashing — HashSLH-DSA (Algorithm 23 of FIPS 205).
    ///
    /// The message is replaced by its digest under `ph`; the library
    /// computes `ph(message)` and embeds the matching OID, forming
    /// `M' = 0x01 || len(ctx) || ctx || OID(ph) || ph(message)`.
    ///
    /// # Arguments
    ///
    /// * `message` - The message to pre-hash and sign (arbitrary length).
    /// * `ctx` - Optional context string, at most 255 bytes (`b""` for none).
    /// * `ph` - The pre-hash function [`PreHash`] applied to `message`.
    /// * `secret_key` - The signing key for this parameter set.
    /// * `rng` - A cryptographic random number generator implementing [`CryptoRng`].
    ///
    /// # Returns
    ///
    /// A [`Signature<P>`] of length [`SlhDsa::signature_size`].
    ///
    /// # Errors
    ///
    /// * [`SlhDsaError::ContextTooLong`] if `ctx` exceeds 255 bytes.
    /// * [`SlhDsaError::RngFailure`] if the RNG cannot provide bytes.
    /// * [`SlhDsaError::FaultDetected`] if the `sca-fors-redundancy` feature is
    ///   enabled and the two independent signing runs disagree.
    pub fn sign_prehash(
        message: &[u8],
        ctx: &[u8],
        ph: PreHash,
        secret_key: &SigningKey<P>,
        rng: &mut dyn CryptoRng,
    ) -> Result<Signature<P>, SlhDsaError> {
        let sig_v = slh::slh_sign_prehash::<P>(message, ctx, ph, secret_key.as_bytes(), rng)?;
        Ok(Signature {
            bytes: sig_v,
            _marker: PhantomData,
        })
    }

    /// Verify a signature on a message with an optional context string.
    ///
    /// Implements Algorithm 24 of FIPS 205 (external SLH-DSA.Verify):
    /// reconstructs `M' = 0x00 || len(ctx) || ctx || message` and checks it.
    /// `ctx` must match the one used at signing time.
    ///
    /// # Arguments
    ///
    /// * `message` - The signed message.
    /// * `ctx` - The context string used during signing, at most 255 bytes.
    /// * `signature` - The signature to check.
    /// * `public_key` - The verifying key for this parameter set.
    ///
    /// # Returns
    ///
    /// `Ok(true)` if the signature is valid, `Ok(false)` if it does not verify.
    ///
    /// # Errors
    ///
    /// * [`SlhDsaError::ContextTooLong`] if `ctx` exceeds 255 bytes.
    /// * [`SlhDsaError::InvalidKey`] if `public_key` has the wrong length.
    /// * [`SlhDsaError::InvalidSignature`] if `signature` has the wrong length.
    pub fn verify(
        message: &[u8],
        ctx: &[u8],
        signature: &Signature<P>,
        public_key: &VerifyingKey<P>,
    ) -> Result<bool, SlhDsaError> {
        slh::slh_verify::<P>(message, signature.as_bytes(), ctx, public_key.as_bytes())
    }

    /// Verify a pre-hash HashSLH-DSA signature (Algorithm 25 of FIPS 205).
    ///
    /// `ph` must match the [`PreHash`] used at signing time.
    ///
    /// # Arguments
    ///
    /// * `message` - The signed message.
    /// * `ctx` - The context string used during signing, at most 255 bytes.
    /// * `ph` - The pre-hash function [`PreHash`], matching the one used at signing.
    /// * `signature` - The signature to check.
    /// * `public_key` - The verifying key for this parameter set.
    ///
    /// # Returns
    ///
    /// `Ok(true)` if the signature is valid, `Ok(false)` if it does not verify.
    ///
    /// # Errors
    ///
    /// * [`SlhDsaError::ContextTooLong`] if `ctx` exceeds 255 bytes.
    /// * [`SlhDsaError::InvalidKey`] if `public_key` has the wrong length.
    /// * [`SlhDsaError::InvalidSignature`] if `signature` has the wrong length.
    pub fn verify_prehash(
        message: &[u8],
        ctx: &[u8],
        ph: PreHash,
        signature: &Signature<P>,
        public_key: &VerifyingKey<P>,
    ) -> Result<bool, SlhDsaError> {
        slh::slh_verify_prehash::<P>(message, signature.as_bytes(), ctx, ph, 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
    }
}