clock_curve_math/
lib.rs

1//! # clock-curve-math
2//!
3//! High-performance, constant-time, cryptography-grade number theory library
4//! for the `ClockCurve` ecosystem.
5//!
6//! ## Overview
7//!
8//! This crate provides:
9//! - Big integer arithmetic with constant-time operations
10//! - Montgomery arithmetic for efficient modular operations
11//! - `FieldElement` modulo p = 2^255 - 19
12//! - Scalar modulo l = 2^252 + 27742317777372353535851937790883648493
13//! - Constant-time helpers for secure computations
14//!
15//! ## Features
16//!
17//! - **`bigint-backend`** (default): Use `clock-bigint` as `BigInt` backend
18//! - **`custom-limbs`**: Use custom limb array implementation
19//! - **`rand`**: Enable random FieldElement/Scalar generation via `clock-rand`
20//! - **`serde`**: Enable serialization/deserialization
21//! - **`alloc`**: Enable heap allocations
22//!
23//! ## Error Handling
24//!
25//! The library provides comprehensive error handling through the [`MathError`] enum.
26//! Most operations that can fail return `Result<T, MathError>`. The library also
27//! provides validation functions for checking inputs before operations.
28//!
29//! ```rust
30//! use clock_curve_math::{FieldElement, MathError, validation};
31//!
32//! // Validate bytes before creating field element
33//! let bytes = [42u8; 32];
34//! validation::validate_field_bytes(&bytes).unwrap();
35//!
36//! // Create field element (will validate internally)
37//! let element = FieldElement::from_bytes(&bytes).unwrap();
38//! ```
39//!
40//! ## Example
41//!
42//! ```rust
43//! use clock_curve_math::{FieldElement, Scalar};
44//!
45//! // Create field elements
46//! let a = FieldElement::from_u64(10);
47//! let b = FieldElement::from_u64(20);
48//!
49//! // Perform operations
50//! let sum = a.add(&b);
51//! let product = a.mul(&b);
52//!
53//! // Create scalars
54//! let s1 = Scalar::from_u64(5);
55//! let s2 = Scalar::from_u64(7);
56//! let product = s1.mul(&s2);
57//! ```
58//!
59//! ## Constant-Time Guarantees
60//!
61//! All operations in this crate execute in constant time to prevent timing attacks.
62//! This includes:
63//! - All arithmetic operations
64//! - All comparisons
65//! - All conditional operations
66//!
67//! ## No-Std Support
68//!
69//! This crate supports `no_std` environments. The `alloc` feature is required
70//! for some operations when using the `bigint-backend` feature.
71
72#![cfg_attr(not(feature = "std"), no_std)]
73#![warn(missing_docs)]
74#![warn(clippy::all)]
75
76// Core modules
77pub mod bigint;
78pub mod constants;
79pub mod ct;
80pub mod error;
81pub mod field;
82pub mod montgomery;
83pub mod scalar;
84pub mod validation;
85
86// Re-exports
87pub use bigint::{BigInt, BigIntOps, ONE, ZERO};
88pub use constants::{L_LIMBS, P_LIMBS};
89pub use error::MathError;
90pub use field::{FieldElement, FieldOps};
91pub use montgomery::{
92    MontgomeryOps, from_montgomery, from_montgomery_l, from_montgomery_p, to_montgomery,
93    to_montgomery_l, to_montgomery_p,
94};
95pub use scalar::{Scalar, ScalarOps};
96pub use validation::{
97    validate_buffer_size, validate_exponent, validate_field_bigint, validate_field_bytes,
98    validate_modulus, validate_non_zero, validate_scalar_bigint, validate_scalar_bytes,
99};
100
101// Constant-time helpers
102pub use ct::{
103    ct_eq, ct_gt, ct_is_zero, ct_lt, ct_mask, ct_neq, ct_select, ct_select_array, ct_swap,
104};
clock_curve_math/lib.rs

clock_curve_math/
lib.rs
