Crate clock_curve_math 

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.

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

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)
let elements = vec![a, b];
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):

[dependencies]
clock-curve-math = { version = "0.6", default-features = false, features = ["custom-limbs"] }

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:

[dependencies]
clock-curve-math = { version = "0.6", default-features = false, features = ["alloc", "custom-limbs"] }

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

Re-exports

pub use bigint::BigInt;

pub use bigint::BigIntOps;

pub use bigint::ONE;

pub use bigint::ZERO;

pub use constants::L_LIMBS;

pub use constants::P_LIMBS;

pub use error::MathError;

pub use field::ExtendedPoint;

pub use field::FieldElement;

pub use field::FieldOps;

pub use montgomery::MontgomeryOps;

pub use montgomery::from_montgomery;

pub use montgomery::from_montgomery_l;

pub use montgomery::from_montgomery_p;

pub use montgomery::to_montgomery;

pub use montgomery::to_montgomery_l;

pub use montgomery::to_montgomery_p;

pub use scalar::Scalar;

pub use scalar::ScalarOps;

pub use validation::validate_buffer_size;

pub use validation::validate_exponent;

pub use validation::validate_field_bigint;

pub use validation::validate_field_bytes;

pub use validation::validate_modulus;

pub use validation::validate_non_zero;

pub use validation::validate_scalar_bigint;

pub use validation::validate_scalar_bytes;

pub use ct::ct_eq;

pub use ct::ct_gt;

pub use ct::ct_is_zero;

pub use ct::ct_lt;

pub use ct::ct_mask;

pub use ct::ct_neq;

pub use ct::ct_select;

pub use ct::ct_select_array;

pub use ct::ct_swap;

Modules

api_extensions

Extended API patterns for future extensibility.

bigint

Big integer arithmetic with constant-time operations.

constants

Mathematical constants for ClockCurve.

ct

Constant-time operations for secure cryptographic computations.

error

Error types for clock-curve-math.

extensible

Extensible arithmetic operations for future cryptographic expansion.

field

Field arithmetic modulo p = 2^255 - 19.

montgomery

Montgomery arithmetic for efficient modular operations.

scalar

Scalar arithmetic modulo l = 2^252 + 27_742_317_777_372_353_535_851_937_790_883_648_493.

validation

Input validation utilities for clock-curve-math.