clock-curve-math 0.5.0

High-performance, constant-time, cryptography-grade number theory library for ClockCurve ecosystem
Documentation

clock-curve-math

Crates.io Documentation License

High-performance, constant-time, cryptography-grade number theory library for the ClockCurve ecosystem.

🎉 Version 0.5.0 - Foundation Release Available! All core arithmetic operations implemented with constant-time guarantees and comprehensive security verification.

Overview

clock-curve-math provides the mathematical foundation for ClockCurve cryptography, implementing:

  • Big integer arithmetic with constant-time operations
  • Montgomery arithmetic for efficient modular operations
  • FieldElement modulo p = 2^255 - 19 (Ed25519 field)
  • Scalar modulo l = 2^252 + 27742317777372353535851937790883648493 (Ed25519 group order)
  • Constant-time helpers for secure computations

All operations are designed for cryptographic security with timing attack resistance.

✅ Version 0.5.0 - Complete

This foundation release includes all core cryptographic operations:

  • ✓ BigInt Operations: Full arithmetic (add, sub, mul, cmp) with constant-time guarantees
  • ✓ Montgomery Arithmetic: Complete REDC algorithm with precomputed constants
  • ✓ FieldElement Operations: All arithmetic (add, sub, mul, inv, pow, square, neg) modulo p
  • ✓ Scalar Operations: All arithmetic (add, sub, mul, inv, pow, square, neg) modulo l
  • ✓ Constant-Time Helpers: ct_eq, ct_neq, ct_lt, ct_gt, ct_select, ct_swap operations
  • ✓ Security Verified: Comprehensive audit with constant-time verification
  • ✓ Cross-Platform: Tested on x86_64, aarch64, riscv64, armv7, powerpc64, embedded targets
  • ✓ Production Ready: No unsafe code, comprehensive error handling, input validation

Features

Backend Options

  • bigint-backend (default): Use clock-bigint for optimized performance
  • custom-limbs: Use custom limb array implementation (fallback)
  • alloc: Heap allocations (required for some operations)
  • std: Standard library support
  • rand: Random generation via clock-rand (future feature)
  • serde: Serialization support (future feature)

Installation

Add this to your Cargo.toml:

[dependencies]
clock-curve-math = "0.5.0"

📦 Latest Release: v0.5.0 - Foundation Release

Feature Flags

For custom backend:

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

Usage

Basic Arithmetic

use clock_curve_math::{FieldElement, Scalar};

// Create field elements (mod p)
let a = FieldElement::from_u64(10);
let b = FieldElement::from_u64(20);

let sum = a.add(&b);
let product = a.mul(&b);

// Create scalars (mod l)
let s1 = Scalar::from_u64(5);
let s2 = Scalar::from_u64(7);

let scalar_product = s1.mul(&s2);

Byte Conversions

use clock_curve_math::FieldElement;

// From canonical bytes (32 bytes)
let bytes = [42u8; 32];
let fe = FieldElement::from_bytes(&bytes).expect("valid bytes");

// Back to bytes
let recovered_bytes = fe.to_bytes();

// From u64
let fe_from_int = FieldElement::from_u64(12345);

Advanced Operations

use clock_curve_math::FieldElement;

let a = FieldElement::from_u64(7);
let b = FieldElement::from_u64(13);

// Modular inverse
let a_inv = a.inv();

// Modular exponentiation
let exp = clock_curve_math::BigInt::from_u64(100);
let result = a.pow(&exp);

// Square root (future feature)

Architecture

clock-curve-math
├── ct/           # Constant-time operations and verification
├── bigint/       # Big integer arithmetic
├── montgomery/   # Montgomery reduction
├── field/        # FieldElement (mod p)
├── scalar/       # Scalar (mod l)
├── validation.rs # Input validation functions
├── error.rs      # Error handling and MathError enum
└── constants.rs  # Mathematical constants

Constant-Time Guarantees

All cryptographic operations execute in constant time regardless of input values:

  • Comparisons use bitwise operations, not branches
  • Conditional operations use masking, not if/else
  • Loop iterations are fixed, not data-dependent
  • All arithmetic avoids secret-dependent branches

Montgomery Arithmetic

The library uses Montgomery form internally for efficient modular multiplication:

// Values are stored in Montgomery representation
let a = FieldElement::from_u64(5);  // Automatically converted to Montgomery form
let b = FieldElement::from_u64(7);
let product = a.mul(&b);            // Montgomery multiplication

Mathematical Constants

Field Modulus (p)

p = 2^255 - 19
  = 57896044618658097711785492504343953926634992332820282019728792003956564819949

Scalar Modulus (l)

l = 2^252 + 27742317777372353535851937790883648493
  = 7237005577332262213973186563042994240857116359379907606001950938285454250989

Security Considerations

See SECURITY.md for comprehensive security documentation including:

  • Constant-Time Guarantees: All operations execute in constant time
  • Threat Model: Attack vectors and mitigation strategies
  • Input Validation: Comprehensive validation prevents invalid states
  • Memory Safety: No unsafe code, Rust's safety guarantees maintained
  • Security Testing: Constant-time verification and vulnerability scanning
  • Hardening Measures: Build and runtime security features

Testing

Run the full test suite:

cargo test

Run with different backends:

# Default backend
cargo test

# Custom limbs backend
cargo test --no-default-features --features custom-limbs,alloc

Test Coverage

  • 152 comprehensive tests covering all functionality
  • Unit tests for all arithmetic operations (add, sub, mul, square, neg, inv, pow)
  • Property-based tests with randomized inputs verifying algebraic properties
  • Edge case testing (zero, one, boundary values, large numbers, invalid inputs)
  • Constant-time verification tests ensuring timing attack resistance
  • Backend compatibility testing across different feature configurations
  • Error handling validation for all public APIs
  • Cross-platform testing for x86_64, aarch64, riscv64, armv7, powerpc64, embedded targets

Benchmarks

Run performance benchmarks:

cargo bench

Benchmarks cover:

  • Arithmetic operations (add, multiply, etc.)
  • Montgomery reduction
  • Modular exponentiation
  • Constant-time verification

Contributing

  1. Follow the SPEC.md specification
  2. Ensure constant-time properties are maintained
  3. Add comprehensive tests for new functionality
  4. Update documentation for API changes

License

Licensed under either of:

at your option.

Changelog

See CHANGELOG.md for detailed release notes and version history.

References