goldilocks_crypto/
lib.rs

1#![forbid(unsafe_code)]
2//! # Goldilocks Crypto
3//!
4//! Rust implementation of ECgFp5 elliptic curve and Schnorr signatures over the Goldilocks field.
5//!
6//! ## ⚠️ Security Warning
7//!
8//! **This library has NOT been audited and is provided as-is. Use with caution.**
9//!
10//! - Prototype implementation focused on correctness
11//! - **Not security audited** - do not use in production without proper security review
12//! - While the implementation appears to work correctly, cryptographic software requires careful auditing
13//! - This is an open-source contribution and not an official Lighter Protocol library
14//! - Use at your own risk
15//!
16//! ## Overview
17//!
18//! This crate provides elliptic curve cryptography primitives specifically designed for
19//! the Goldilocks field, including:
20//!
21//! - **ECgFp5 Elliptic Curve**: Point operations over the Fp5 extension field
22//! - **Schnorr Signatures**: Signature generation and verification using Poseidon2 hashing
23//! - **Scalar Field**: Efficient scalar operations for private keys and nonces
24//! - **Point Arithmetic**: Addition, multiplication, encoding, and decoding
25//!
26//! ## Dependencies
27//!
28//! This crate depends on [`poseidon-hash`] for:
29//! - Goldilocks field arithmetic
30//! - Poseidon2 hash function
31//! - Fp5 extension field operations
32//!
33//! ## Example
34//!
35//! ```rust
36//! use goldilocks_crypto::{ScalarField, Point, sign, verify_signature};
37//!
38//! // Generate a random private key
39//! let private_key = ScalarField::sample_crypto();
40//! let private_key_bytes = private_key.to_bytes_le();
41//!
42//! // Derive public key
43//! let public_key = Point::generator().mul(&private_key);
44//! let public_key_bytes = public_key.encode().to_bytes_le();
45//!
46//! // Sign a message (nonce is generated internally)
47//! let message = [0u8; 40];
48//! let signature = sign(&private_key_bytes, &message).unwrap();
49//!
50//! // Verify signature
51//! let is_valid = verify_signature(&signature, &message, &public_key_bytes).unwrap();
52//! assert!(is_valid);
53//! ```
54//!
55//! [`poseidon-hash`]: https://crates.io/crates/poseidon-hash
56
57pub mod schnorr;
58pub mod scalar_field;
59pub mod batch_verify;
60pub mod signature;
61pub mod keypair;
62
63pub use scalar_field::ScalarField;
64
65pub use poseidon_hash::{Goldilocks, Fp5Element};
66
67// Re-export Schnorr functions
68pub use schnorr::{sign, sign_with_nonce, verify_signature, validate_public_key, sign_hashed_message, Point, AffinePoint};
69pub use batch_verify::batch_verify;
70pub use signature::Signature;
71pub use keypair::KeyPair;
72// WeierstrassPoint will be added when needed - for now using Point::mul_add2 for verification
73pub type WeierstrassPoint = Point;
74
75use thiserror::Error;
76
77/// Errors that can occur during cryptographic operations.
78#[derive(Error, Debug)]
79pub enum CryptoError {
80    /// The private key has an invalid length.
81    #[error("Invalid private key length: expected 40 bytes, got {0}")]
82    InvalidPrivateKeyLength(usize),
83    /// The signature format is invalid.
84    #[error("Invalid signature format")]
85    InvalidSignature,
86    /// The signature has an invalid length.
87    #[error("Invalid signature length: expected 80 bytes, got {0}")]
88    InvalidSignatureLength(usize),
89    /// The message has an invalid length.
90    #[error("Invalid message length: expected 40 bytes, got {0}")]
91    InvalidMessageLength(usize),
92    /// The public key is invalid or cannot be decoded.
93    #[error("Invalid public key: cannot decode as encoded point")]
94    InvalidPublicKey,
95    /// Hex decoding failed.
96    #[error("Hex decode error: {0}")]
97    HexDecode(#[from] hex::FromHexError),
98    /// A message 8-byte chunk represents a value ≥ the Goldilocks field modulus.
99    /// Messages must be formed from canonical Goldilocks field elements
100    /// (each 8-byte little-endian chunk must be in [0, 2¶⁴ − 2³² + 1)).
101    #[error("Non-canonical message: chunk {index} value 0x{value:016x} is >= Goldilocks modulus")]
102    NonCanonicalMessage { index: usize, value: u64 },
103}
104
105/// Result type for cryptographic operations.
106pub type Result<T> = std::result::Result<T, CryptoError>;
107
goldilocks_crypto/lib.rs

goldilocks_crypto/
lib.rs
