clock_curve_math/

lib.rs

//! # clock-curve-math
//!
//! High-performance, constant-time, cryptography-grade number theory library
//! for the `ClockCurve` ecosystem.
//!
//! ## Overview
//!
//! This crate provides:
//! - Big integer arithmetic with constant-time operations
//! - Montgomery arithmetic for efficient modular operations
//! - `FieldElement` modulo p = 2^255 - 19
//! - Scalar modulo l = 2^252 + 27_742_317_777_372_353_535_851_937_790_883_648_493
//! - Constant-time helpers for secure computations
//!
//! ## Features
//!
//! ### Backend Selection (choose one)
//! - **`bigint-backend`** (default): Use `clock-bigint` for high-performance BigInt operations
//! - **`custom-limbs`**: Pure Rust limb array implementation (no_std compatible)
//!
//! ### Optional Features
//! - **`rand`**: Random FieldElement/Scalar generation via `clock-rand`
//! - **`serde`**: Serialization/deserialization support
//!
//! ### Memory Management
//! - **`alloc`** (default): Enable heap allocations for advanced operations
//! - **`std`**: Enable full standard library support
//!
//! ### Feature Combinations
//! | Environment | Features | Description |
//! |-------------|----------|-------------|
//! | Full std | default | All features, maximum functionality |
//! | Embedded no_std | `custom-limbs` | Minimal footprint, no heap allocation |
//! | Embedded with alloc | `alloc,custom-limbs` | Heap allocation, advanced operations |
//! | Server with custom backend | `std,custom-limbs` | Full std, custom BigInt implementation |
//!
//! ## Error Handling
//!
//! The library provides comprehensive error handling through the [`MathError`] enum.
//! Most operations that can fail return `Result<T, MathError>`. The library also
//! provides validation functions for checking inputs before operations.
//!
//! ```rust
//! use clock_curve_math::{FieldElement, MathError, validation};
//!
//! // Validate bytes before creating field element
//! let bytes = [42u8; 32];
//! validation::validate_field_bytes(&bytes).unwrap();
//!
//! // Create field element (will validate internally)
//! let element = FieldElement::from_bytes(&bytes).unwrap();
//! ```
//!
//! ## Example
//!
//! ```rust
//! use clock_curve_math::{FieldElement, Scalar, FieldOps, ScalarOps};
//!
//! // Create field elements
//! let a = FieldElement::from_u64(10);
//! let b = FieldElement::from_u64(20);
//!
//! // Perform operations
//! let sum = a.add(&b);
//! let product = a.mul(&b);
//!
//! // Create scalars
//! let s1 = Scalar::from_u64(5);
//! let s2 = Scalar::from_u64(7);
//! let scalar_product = s1.mul(&s2);
//!
//! // Advanced operations (require alloc feature)
//! # #[cfg(feature = "alloc")]
//! let elements = vec![a, b];
//! # #[cfg(feature = "alloc")]
//! let inverses = clock_curve_math::field::batch_inverse(&elements).unwrap();
//! ```
//!
//! ## Constant-Time Guarantees
//!
//! All operations in this crate execute in constant time to prevent timing attacks.
//! This includes:
//! - All arithmetic operations
//! - All comparisons
//! - All conditional operations
//!
//! ## No-Std Support
//!
//! This crate supports `no_std` environments with flexible feature configurations:
//!
//! ### Minimal no_std Configuration
//! For the most constrained environments (embedded systems, kernels):
//!
//! ```toml
//! [dependencies]
//! clock-curve-math = { version = "0.6", default-features = false, features = ["custom-limbs"] }
//! ```
//!
//! ```rust,no_run
//! use clock_curve_math::{FieldElement, Scalar, FieldOps, ScalarOps};
//!
//! // Basic operations work without heap allocation
//! let a = FieldElement::from_u64(42);
//! let b = FieldElement::from_u64(24);
//! let sum = a.add(&b);
//! let product = a.mul(&b);
//! ```
//!
//! ### With Heap Allocation
//! For environments with allocators but no full std:
//!
//! ```toml
//! [dependencies]
//! clock-curve-math = { version = "0.6", default-features = false, features = ["alloc", "custom-limbs"] }
//! ```
//!
//! ```rust,no_run
//! use clock_curve_math::{FieldElement, field};
//!
//! // Advanced operations requiring allocation
//! let elements = vec![FieldElement::from_u64(1), FieldElement::from_u64(2)];
//! let inverses = field::batch_inverse(&elements).unwrap();
//! ```
//!
//! ### Backend Options
//! - **`custom-limbs`**: Pure no_std, no external dependencies
//! - **`bigint-backend`**: Uses `clock-bigint` (requires `alloc`)
//!
//! ### Cross-Platform Compatibility
//! Tested architectures: x86_64, aarch64, riscv64gc, armv7, powerpc64, thumbv7em, thumbv8m

#![cfg_attr(not(feature = "std"), no_std)]
#![warn(missing_docs)]
#![warn(clippy::all)]

// Core modules
pub mod api_extensions;
pub mod bigint;
pub mod constants;
pub mod ct;
pub mod error;
pub mod extensible;
pub mod field;
pub mod montgomery;
pub mod scalar;
pub mod validation;

// SIMD preparation module (future optimization)
#[cfg(feature = "simd")]
pub mod simd;

// Re-exports
pub use bigint::{BigInt, BigIntOps, ONE, ZERO};
pub use constants::{L_LIMBS, P_LIMBS};
pub use error::MathError;
pub use field::{ExtendedPoint, FieldElement, FieldOps};
pub use montgomery::{
    MontgomeryOps, from_montgomery, from_montgomery_l, from_montgomery_p, to_montgomery,
    to_montgomery_l, to_montgomery_p,
};
pub use scalar::{Scalar, ScalarOps};
pub use validation::{
    validate_buffer_size, validate_exponent, validate_field_bigint, validate_field_bytes,
    validate_modulus, validate_non_zero, validate_scalar_bigint, validate_scalar_bytes,
};

// Serde re-exports (when serde feature is enabled)
#[cfg(feature = "serde")]
pub use {serde::Deserialize, serde::Serialize};

// Constant-time helpers
pub use ct::{
    ct_eq, ct_gt, ct_is_zero, ct_lt, ct_mask, ct_neq, ct_select, ct_select_array, ct_swap,
};