clock-curve-math 0.5.0

# clock-curve-math

[![Crates.io](https://img.shields.io/crates/v/clock-curve-math.svg)](https://crates.io/crates/clock-curve-math)
[![Documentation](https://docs.rs/clock-curve-math/badge.svg)](https://docs.rs/clock-curve-math)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/Olyntar-Labs/clock-curve-math)

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`:

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

📦 **Latest Release**: [v0.5.0 - Foundation Release](https://github.com/Olyntar-Labs/clock-curve-math/releases/tag/v0.5.0)

### Feature Flags

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

## Usage

### Basic Arithmetic

```rust
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

```rust
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

```rust
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:

```rust
// 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](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:

```bash
cargo test
```

Run with different backends:

```bash
# 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:

```bash
cargo bench
```

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

## Contributing

1. Follow the [SPEC.md](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:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT License ([LICENSE-MIT](LICENSE-MIT))

at your option.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for detailed release notes and version history.

## References

- [Ed25519 specification (RFC 8032)](https://tools.ietf.org/html/rfc8032)
- [Curve25519 specification](https://cr.yp.to/ecdh/curve25519-20060209.pdf)
- [Montgomery, P. L. "Modular multiplication without trial division" (1985)](https://www.ams.org/journals/mcom/1985-44-170/S0025-5718-1985-0777282-X/S0025-5718-1985-0777282-X.pdf)