clock_curve_math/
error.rs

1//! Error types for clock-curve-math.
2//!
3//! This module defines the comprehensive error types used throughout
4//! the clock-curve-math library for cryptographic operations.
5//!
6//! ## Error Categories
7//!
8//! Errors are categorized by the type of validation or operation failure:
9//!
10//! ### Input Validation Errors
11//! - [`MathError::InvalidBytes`]: Byte representation out of valid range
12//! - [`MathError::InvalidInput`]: General invalid input parameter
13//! - [`MathError::InvalidFieldElement`]: Field element not in [0, p)
14//! - [`MathError::InvalidScalar`]: Scalar not in [0, l)
15//! - [`MathError::InvalidExponent`]: Invalid exponent for exponentiation
16//! - [`MathError::InvalidModulus`]: Invalid modulus for modular operations
17//! - [`MathError::InvalidEncoding`]: Invalid encoding format
18//!
19//! ### Buffer Errors
20//! - [`MathError::BufferTooSmall`]: Input buffer smaller than required size
21//! - [`MathError::BufferTooLarge`]: Input buffer larger than required size
22//!
23//! ### Arithmetic Errors
24//! - [`MathError::DivisionByZero`]: Attempted division by zero or modular inverse of zero
25//! - [`MathError::Overflow`]: Arithmetic overflow in operations
26//! - [`MathError::Underflow`]: Arithmetic underflow in operations
27//!
28//! ### Future Extension Errors
29//! - [`MathError::PointNotOnCurve`]: Point not on elliptic curve (for future EC operations)
30//! - [`MathError::InvalidMontgomeryForm`]: Invalid Montgomery form representation
31//!
32//! ## Error Handling
33//!
34//! Most operations return `Result<T, MathError>` to allow callers to handle
35//! errors appropriately. Some operations (like basic arithmetic) may panic
36//! on invalid inputs for security reasons, while others provide checked
37//! variants that return errors.
38//!
39//! ```rust
40//! use clock_curve_math::{FieldElement, MathError};
41//!
42//! // Operations that return errors
43//! let result = FieldElement::from_bytes(&[0u8; 32]);
44//! match result {
45//!     Ok(element) => println!("Valid field element: {:?}", element),
46//!     Err(MathError::InvalidFieldElement) => println!("Invalid field element"),
47//!     Err(e) => println!("Other error: {:?}", e),
48//! }
49//! ```
50
51/// Errors that can occur in mathematical operations.
52#[derive(Debug, Clone, PartialEq, Eq)]
53pub enum MathError {
54    /// Invalid byte representation (out of valid range)
55    InvalidBytes,
56    /// General invalid input
57    InvalidInput,
58    /// Attempted division by zero
59    DivisionByZero,
60    /// Arithmetic overflow
61    Overflow,
62    /// Arithmetic underflow
63    Underflow,
64    /// Invalid field element (not in [0, p))
65    InvalidFieldElement,
66    /// Invalid scalar (not in [0, l))
67    InvalidScalar,
68    /// Invalid exponent for modular exponentiation
69    InvalidExponent,
70    /// Invalid modulus for modular operations
71    InvalidModulus,
72    /// Invalid encoding format
73    InvalidEncoding,
74    /// Buffer too small for operation
75    BufferTooSmall,
76    /// Buffer too large for operation
77    BufferTooLarge,
78    /// Point not on elliptic curve (for future EC operations)
79    PointNotOnCurve,
80    /// Invalid extended point coordinates (T ≠ X·Y·Z⁻¹)
81    InvalidPoint,
82    /// Invalid Montgomery form representation
83    InvalidMontgomeryForm,
84    /// Operation not yet implemented
85    NotImplemented,
86}
87
88impl core::fmt::Display for MathError {
89    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
90        match self {
91            MathError::InvalidBytes => write!(f, "Invalid byte representation"),
92            MathError::InvalidInput => write!(f, "Invalid input"),
93            MathError::DivisionByZero => write!(f, "Division by zero"),
94            MathError::Overflow => write!(f, "Arithmetic overflow"),
95            MathError::Underflow => write!(f, "Arithmetic underflow"),
96            MathError::InvalidFieldElement => write!(f, "Invalid field element (not in [0, p))"),
97            MathError::InvalidScalar => write!(f, "Invalid scalar (not in [0, l))"),
98            MathError::InvalidExponent => write!(f, "Invalid exponent for modular exponentiation"),
99            MathError::InvalidModulus => write!(f, "Invalid modulus for modular operations"),
100            MathError::InvalidEncoding => write!(f, "Invalid encoding format"),
101            MathError::BufferTooSmall => write!(f, "Buffer too small for operation"),
102            MathError::BufferTooLarge => write!(f, "Buffer too large for operation"),
103            MathError::PointNotOnCurve => write!(f, "Point not on elliptic curve"),
104            MathError::InvalidPoint => write!(f, "Invalid extended point coordinates (T ≠ X·Y·Z⁻¹)"),
105            MathError::InvalidMontgomeryForm => write!(f, "Invalid Montgomery form representation"),
106            MathError::NotImplemented => write!(f, "Operation not yet implemented"),
107        }
108    }
109}
110
111#[cfg(feature = "std")]
112impl std::error::Error for MathError {}
clock_curve_math/error.rs

clock_curve_math/
error.rs
