clock_curve_math/

validation.rs

//! Input validation utilities for clock-curve-math.
//!
//! This module provides comprehensive validation functions for all public APIs
//! to ensure inputs are within valid ranges and prevent invalid operations.
//!
//! ## Validation Functions
//!
//! The validation functions check that inputs conform to the mathematical
//! constraints of the cryptographic primitives:
//!
//! - **Field elements** must be in the range [0, p) where p = 2^255 - 19
//! - **Scalars** must be in the range [0, l) where l = 2^252 + 27742317777372353535851937790883648493
//! - **Exponents** must be non-negative (though BigInt always represents non-negative values)
//! - **Moduli** must be positive and non-zero
//! - **Buffers** must have the correct size for the operation
//!
//! ## Error Conditions
//!
//! All validation functions return [`MathError`] variants that precisely
//! describe the validation failure:
//!
//! - [`MathError::InvalidFieldElement`]: Value not in [0, p)
//! - [`MathError::InvalidScalar`]: Value not in [0, l)
//! - [`MathError::InvalidExponent`]: Negative exponent provided
//! - [`MathError::InvalidModulus`]: Zero or negative modulus
//! - [`MathError::BufferTooSmall`]: Input buffer smaller than required
//! - [`MathError::BufferTooLarge`]: Input buffer larger than required
//!
//! ## Usage
//!
//! ```rust
//! use clock_curve_math::validation::*;
//!
//! // Validate a field element byte representation
//! let bytes = [42u8; 32];
//! assert!(validate_field_bytes(&bytes).is_ok());
//!
//! // Validate a scalar BigInt value
//! let scalar_value = clock_curve_math::BigInt::from_u64(12345);
//! assert!(validate_scalar_bigint(&scalar_value).is_ok());
//! ```

use crate::bigint::BigInt;
use crate::constants::{L_LIMBS, P_LIMBS};
use crate::error::MathError;

/// Validate that a byte array represents a valid field element (in [0, p)).
///
/// # Arguments
///
/// * `bytes` - The byte array to validate (must be 32 bytes)
///
/// # Returns
///
/// Returns `Ok(())` if the bytes represent a valid field element, or an error otherwise.
///
/// # Errors
///
/// Returns [`MathError::InvalidFieldElement`] if the value is not in [0, p).
/// Returns [`MathError::BufferTooSmall`] or [`MathError::BufferTooLarge`] if the buffer size is incorrect.
pub fn validate_field_bytes(bytes: &[u8]) -> Result<(), MathError> {
    if bytes.len() != 32 {
        return if bytes.len() < 32 {
            Err(MathError::BufferTooSmall)
        } else {
            Err(MathError::BufferTooLarge)
        };
    }

    // SAFETY: We just checked that bytes.len() == 32
    let bytes_array: &[u8; 32] = bytes.try_into().unwrap();
    let value = BigInt::from_bytes(bytes_array);
    let p = BigInt::from_limbs(&P_LIMBS);

    if value.cmp(&p) != core::cmp::Ordering::Less {
        return Err(MathError::InvalidFieldElement);
    }

    Ok(())
}

/// Validate that a byte array represents a valid scalar (in [0, l)).
///
/// # Arguments
///
/// * `bytes` - The byte array to validate (must be 32 bytes)
///
/// # Returns
///
/// Returns `Ok(())` if the bytes represent a valid scalar, or an error otherwise.
///
/// # Errors
///
/// Returns [`MathError::InvalidScalar`] if the value is not in [0, l).
/// Returns [`MathError::BufferTooSmall`] or [`MathError::BufferTooLarge`] if the buffer size is incorrect.
pub fn validate_scalar_bytes(bytes: &[u8]) -> Result<(), MathError> {
    if bytes.len() != 32 {
        return if bytes.len() < 32 {
            Err(MathError::BufferTooSmall)
        } else {
            Err(MathError::BufferTooLarge)
        };
    }

    // SAFETY: We just checked that bytes.len() == 32
    let bytes_array: &[u8; 32] = bytes.try_into().unwrap();
    let value = BigInt::from_bytes(bytes_array);
    let l = BigInt::from_limbs(&L_LIMBS);

    if value.cmp(&l) != core::cmp::Ordering::Less {
        return Err(MathError::InvalidScalar);
    }

    Ok(())
}

/// Validate that a BigInt represents a valid field element (in [0, p)).
///
/// # Arguments
///
/// * `value` - The BigInt value to validate
///
/// # Returns
///
/// Returns `Ok(())` if the value is a valid field element, or an error otherwise.
///
/// # Errors
///
/// Returns [`MathError::InvalidFieldElement`] if the value is not in [0, p).
pub fn validate_field_bigint(value: &BigInt) -> Result<(), MathError> {
    let p = BigInt::from_limbs(&P_LIMBS);

    // Check value < p (BigInt values are always >= 0)
    if value.cmp(&p) != core::cmp::Ordering::Less {
        return Err(MathError::InvalidFieldElement);
    }

    Ok(())
}

/// Validate that a BigInt represents a valid scalar (in [0, l)).
///
/// # Arguments
///
/// * `value` - The BigInt value to validate
///
/// # Returns
///
/// Returns `Ok(())` if the value is a valid scalar, or an error otherwise.
///
/// # Errors
///
/// Returns [`MathError::InvalidScalar`] if the value is not in [0, l).
pub fn validate_scalar_bigint(value: &BigInt) -> Result<(), MathError> {
    let l = BigInt::from_limbs(&L_LIMBS);

    // Check value < l (BigInt values are always >= 0)
    if value.cmp(&l) != core::cmp::Ordering::Less {
        return Err(MathError::InvalidScalar);
    }

    Ok(())
}

/// Validate that a BigInt is a valid exponent for modular exponentiation.
///
/// # Arguments
///
/// * `exponent` - The exponent to validate
///
/// # Returns
///
/// Returns `Ok(())` if the exponent is valid, or an error otherwise.
///
/// # Errors
///
/// Returns [`MathError::InvalidExponent`] if the exponent is negative.
pub fn validate_exponent(exponent: &BigInt) -> Result<(), MathError> {
    if exponent.cmp(&crate::ZERO()) == core::cmp::Ordering::Less {
        return Err(MathError::InvalidExponent);
    }

    Ok(())
}

/// Validate that a BigInt is a valid modulus for modular operations.
///
/// # Arguments
///
/// * `modulus` - The modulus to validate
///
/// # Returns
///
/// Returns `Ok(())` if the modulus is valid, or an error otherwise.
///
/// # Errors
///
/// Returns [`MathError::InvalidModulus`] if the modulus is zero or negative.
pub fn validate_modulus(modulus: &BigInt) -> Result<(), MathError> {
    if modulus.cmp(&crate::ZERO()) != core::cmp::Ordering::Greater {
        return Err(MathError::InvalidModulus);
    }

    Ok(())
}

/// Validate that a value is not zero (for operations that require non-zero inputs).
///
/// # Arguments
///
/// * `value` - The value to check
/// * `_operation` - Description of the operation requiring non-zero input (currently unused)
///
/// # Returns
///
/// Returns `Ok(())` if the value is non-zero, or an error otherwise.
///
/// # Errors
///
/// Returns [`MathError::DivisionByZero`] if the value is zero.
pub fn validate_non_zero(value: &BigInt, _operation: &str) -> Result<(), MathError> {
    if value.is_zero() {
        // Note: DivisionByZero is used here even for operations other than division
        // that require non-zero inputs (like modular inverse)
        return Err(MathError::DivisionByZero);
    }

    Ok(())
}

/// Validate buffer size for byte array operations.
///
/// # Arguments
///
/// * `buffer` - The buffer to validate
/// * `expected_size` - The expected buffer size
///
/// # Returns
///
/// Returns `Ok(())` if the buffer size is correct, or an error otherwise.
///
/// # Errors
///
/// Returns [`MathError::BufferTooSmall`] or [`MathError::BufferTooLarge`] if the buffer size is incorrect.
pub fn validate_buffer_size(buffer: &[u8], expected_size: usize) -> Result<(), MathError> {
    if buffer.len() != expected_size {
        return if buffer.len() < expected_size {
            Err(MathError::BufferTooSmall)
        } else {
            Err(MathError::BufferTooLarge)
        };
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::bigint::BigInt;

    #[test]
    fn test_validate_field_bytes_valid() {
        let bytes = [42u8; 32];
        assert!(validate_field_bytes(&bytes).is_ok());
    }

    #[test]
    fn test_validate_field_bytes_invalid_too_large() {
        // p = 2^255 - 19, so any value >= p should be invalid
        let p_bytes = [
            0xED, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
            0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x7F
        ];
        assert!(matches!(validate_field_bytes(&p_bytes), Err(MathError::InvalidFieldElement)));
    }

    #[test]
    fn test_validate_field_bytes_wrong_size() {
        let small_buffer = [42u8; 16];
        assert!(matches!(validate_field_bytes(&small_buffer), Err(MathError::BufferTooSmall)));

        let large_buffer = [42u8; 64];
        assert!(matches!(validate_field_bytes(&large_buffer), Err(MathError::BufferTooLarge)));
    }

    #[test]
    fn test_validate_scalar_bytes_valid() {
        // Use a small value that is definitely < l
        let mut bytes = [0u8; 32];
        bytes[0] = 42; // Only the least significant byte is non-zero
        assert!(validate_scalar_bytes(&bytes).is_ok());
    }

    #[test]
    fn test_validate_scalar_bytes_invalid_too_large() {
        // Create bytes that represent a value >= l
        let large_bytes = [0xFF; 32];
        // This will likely be >= l, but let's test it
        let result = validate_scalar_bytes(&large_bytes);
        // It might be valid or invalid depending on the exact value, but shouldn't panic
        assert!(result.is_ok() || matches!(result, Err(MathError::InvalidScalar)));
    }

    #[test]
    fn test_validate_field_bigint_valid() {
        let value = BigInt::from_u64(42);
        assert!(validate_field_bigint(&value).is_ok());
    }

    #[test]
    fn test_validate_field_bigint_too_large() {
        let p = BigInt::from_limbs(&P_LIMBS);
        let too_large = p.add(&BigInt::from_u64(1));
        assert!(matches!(validate_field_bigint(&too_large), Err(MathError::InvalidFieldElement)));
    }

    #[test]
    fn test_validate_exponent_negative() {
        // BigInt doesn't support negative numbers, so we test with a large positive number
        // that would underflow if it were negative
        let large_value = BigInt::from_limbs(&[u64::MAX, u64::MAX, u64::MAX, u64::MAX]);
        // This should pass since BigInt treats all values as positive
        assert!(validate_exponent(&large_value).is_ok());
    }

    #[test]
    fn test_validate_exponent_zero() {
        let zero = BigInt::from_u64(0);
        assert!(validate_exponent(&zero).is_ok());
    }

    #[test]
    fn test_validate_modulus_zero() {
        let zero = BigInt::from_u64(0);
        assert!(matches!(validate_modulus(&zero), Err(MathError::InvalidModulus)));
    }

    #[test]
    fn test_validate_modulus_large_positive() {
        // Test with a modulus that's actually valid (non-zero)
        let valid_modulus = BigInt::from_u64(17);
        assert!(validate_modulus(&valid_modulus).is_ok());
    }

    #[test]
    fn test_validate_non_zero() {
        let zero = BigInt::from_u64(0);
        assert!(matches!(validate_non_zero(&zero, "test"), Err(MathError::DivisionByZero)));

        let non_zero = BigInt::from_u64(42);
        assert!(validate_non_zero(&non_zero, "test").is_ok());
    }
}