Secret split (#59)

Author: davxy

Cargo.toml

@@ -44,6 +44,7 @@ std = [
   "ark-ec/std",
   "ring-proof?/std",
 ]
+secret-split = [ "ark-std/getrandom" ]
 full = [
   "secp256r1",
   "ed25519",

README.md

@@ -21,7 +21,7 @@ supports customization of scheme parameters.
 
 ### Built-In suites
 
-The library includes the following pre-configured suites:
+The library conditionally includes the following pre-configured suites (see features section):
 
 - **Ed25519-SHA-512-TAI**: Supports IETF and Pedersen VRFs.
 - **Secp256r1-SHA-256-TAI**: Supports IETF and Pedersen VRFs.
@@ -41,21 +41,21 @@ let aux_data = b"optional aux data";
 ```
 #### IETF-VRF
 
-Prove
+_Prove_
 ```rust
 use ark_ec_vrfs::ietf::Prover;
 let proof = secret.prove(input, output, aux_data);
 ```
 
-Verify
+_Verify_
 ```rust
 use ark_ec_vrfs::ietf::Verifier;
 let result = public.verify(input, output, aux_data, &proof);
 ```
 
 #### Ring-VRF
 
-Ring construction
+_Ring construction_
 ```rust
 const RING_SIZE: usize = 100;
 let prover_key_index = 3;
@@ -67,33 +67,57 @@ ring[prover_key_index] = public.0;
 ring[0] = RingContext::padding_point();
 ```
 
-Ring context construction
+_Ring parameters construction_
 ```rust
 let ring_ctx = RingContext::from_seed(RING_SIZE, b"example seed");
 ```
 
-Prove
+_Prove_
 ```rust
 use ark_ec_vrfs::ring::Prover;
 let prover_key = ring_ctx.prover_key(&ring);
 let prover = ring_ctx.prover(prover_key, prover_key_index);
 let proof = secret.prove(input, output, aux_data, &prover);
 ```
 
-Verify
+_Verify_
 ```rust
 use ark_ec_vrfs::ring::Verifier;
 let verifier_key = ring_ctx.verifier_key(&ring);
 let verifier = ring_ctx.verifier(verifier_key);
 let result = Public::verify(input, output, aux_data, &proof, &verifier);
 ```
 
-Verifier key from commitment
+_Verifier key from commitment_
 ```rust
 let ring_commitment = ring_ctx.verifier_key().commitment();
 let verifier_key = ring_ctx.verifier_key_from_commitment(ring_commitment);
 ```
 
+## Features
+
+- `default`: `std`
+- `full`: Enables all features listed below except `secret-split`, `parallel`, `asm`, `rfc-6979`, `test-vectors`.
+- `secret-split`: Point scalar multiplication with secret split. Secret scalar is split into the sum
+   of two scalars, which randomly mutate but retain the same sum. Incurs 2x penalty in some internal
+   sensible scalar multiplications, but provides side channel defenses.
+- `ring`: Ring-VRF for the curves supporting it.
+- `rfc-6979`: Support for nonce generation according to RFC-9381 section 5.4.2.1.
+- `test-vectors`: Deterministic ring-vrf proof. Useful for reproducible test vectors generation.
+
+### Curves
+
+- `ed25519`
+- `jubjub`
+- `bandersnatch`
+- `baby-jubjub`
+- `secp256r1`
+
+### Arkworks optimizations
+
+- `parallel`: Parallel execution where worth using `rayon`.
+- `asm`: Assembly implementation of some low level operations.
+
 ## License
 
-Distributed under the [MIT License](LICENSE).
+Distributed under the [MIT License](./LICENSE).

src/codec.rs

@@ -1,3 +1,5 @@
+//! Points and scalars encoding.
+
 use ark_ec::short_weierstrass::SWCurveConfig;
 use utils::te_sw_map;
 

src/ietf.rs

@@ -90,9 +90,9 @@ pub trait Verifier<S: IetfSuite> {
 impl<S: IetfSuite> Prover<S> for Secret<S> {
     fn prove(&self, input: Input<S>, output: Output<S>, ad: impl AsRef<[u8]>) -> Proof<S> {
         let k = S::nonce(&self.scalar, input);
-        let k_b = (S::generator() * k).into_affine();
 
-        let k_h = (input.0 * k).into_affine();
+        let k_b = smul!(S::generator(), k).into_affine();
+        let k_h = smul!(input.0, k).into_affine();
 
         let c = S::challenge(
             &[&self.public.0, &input.0, &output.0, &k_b, &k_h],

src/lib.rs

@@ -1,4 +1,4 @@
-//! # Elliptic Curve VRFs.
+//! # Elliptic Curve VRF-AD
 //!
 //! This library provides flexible and efficient implementations of Verifiable
 //! Random Functions with Additional Data (VRF-AD), a cryptographic construct
@@ -8,22 +8,130 @@
 //! It leverages the [Arkworks](https://github.com/arkworks-rs) framework and
 //! supports customization of scheme parameters.
 //!
-//! Supported VRFs:
+//! ### Supported VRFs
+//!
 //! - **IETF VRF**: Complies with ECVRF described in [RFC9381](https://datatracker.ietf.org/doc/rfc9381).
 //! - **Pedersen VRF**: Described in [BCHSV23](https://eprint.iacr.org/2023/002).
 //! - **Ring VRF**: A zero-knowledge-based inspired by [BCHSV23](https://eprint.iacr.org/2023/002).
+//!
+//! ### Schemes Specifications
+//!
+//! - [VRF Schemes Details](https://github.com/davxy/bandersnatch-vrfs-spec)
+//! - [Ring VRF ZK Proof](https://github.com/davxy/ring-proof-spec)
+//!
+//! ### Built-In suites
+//!
+//! The library conditionally includes the following pre-configured suites (see features section):
+//!
+//! - **Ed25519-SHA-512-TAI**: Supports IETF and Pedersen VRFs.
+//! - **Secp256r1-SHA-256-TAI**: Supports IETF and Pedersen VRFs.
+//! - **Bandersnatch** (_Edwards curve on BLS12-381_): Supports IETF, Pedersen, and Ring VRFs.
+//! - **JubJub** (_Edwards curve on BLS12-381_): Supports IETF, Pedersen, and Ring VRFs.
+//! - **Baby-JubJub** (_Edwards curve on BN254_): Supports IETF, Pedersen, and Ring VRFs.
+//!
+//! ### Basic Usage
+//!
+//! ```rust,ignore
+//! use ark_ec_vrfs::suites::bandersnatch::*;
+//! let secret = Secret::from_seed(b"example seed");
+//! let public = secret.public();
+//! let input = Input::new(b"example input").unwrap();
+//! let output = secret.output(input);
+//! let aux_data = b"optional aux data";
+//! ```
+//! #### IETF-VRF
+//!
+//! _Prove_
+//! ```rust,ignore
+//! use ark_ec_vrfs::ietf::Prover;
+//! let proof = secret.prove(input, output, aux_data);
+//! ```
+//!
+//! _Verify_
+//! ```rust,ignore
+//! use ark_ec_vrfs::ietf::Verifier;
+//! let result = public.verify(input, output, aux_data, &proof);
+//! ```
+//!
+//! #### Ring-VRF
+//!
+//! _Ring construction_
+//! ```rust,ignore
+//! const RING_SIZE: usize = 100;
+//! let prover_key_index = 3;
+//! // Construct an example ring with dummy keys
+//! let mut ring = (0..RING_SIZE).map(|i| Secret::from_seed(&i.to_le_bytes()).public().0).collect();
+//! // Patch the ring with the public key of the prover
+//! ring[prover_key_index] = public.0;
+//! // Any key can be replaced with the padding point
+//! ring[0] = RingContext::padding_point();
+//! ```
+//!
+//! _Ring parameters construction_
+//! ```rust,ignore
+//! let ring_ctx = RingContext::from_seed(RING_SIZE, b"example seed");
+//! ```
+//!
+//! _Prove_
+//! ```rust,ignore
+//! use ark_ec_vrfs::ring::Prover;
+//! let prover_key = ring_ctx.prover_key(&ring);
+//! let prover = ring_ctx.prover(prover_key, prover_key_index);
+//! let proof = secret.prove(input, output, aux_data, &prover);
+//! ```
+//!
+//! _Verify_
+//! ```rust,ignore
+//! use ark_ec_vrfs::ring::Verifier;
+//! let verifier_key = ring_ctx.verifier_key(&ring);
+//! let verifier = ring_ctx.verifier(verifier_key);
+//! let result = Public::verify(input, output, aux_data, &proof, &verifier);
+//! ```
+//!
+//! _Verifier key from commitment_
+//! ```rust,ignore
+//! let ring_commitment = ring_ctx.verifier_key().commitment();
+//! let verifier_key = ring_ctx.verifier_key_from_commitment(ring_commitment);
+//! ```
+//!
+//! ## Features
+//!
+//! - `default`: `std`
+//! - `full`: Enables all features listed below except `secret-split`, `parallel`, `asm`, `rfc-6979`, `test-vectors`.
+//! - `secret-split`: Point scalar multiplication with secret split. Secret scalar is split into the sum
+//!    of two scalars, which randomly mutate but retain the same sum. Incurs 2x penalty in some internal
+//!    sensible scalar multiplications, but provides side channel defenses.
+//! - `ring`: Ring-VRF for the curves supporting it.
+//! - `rfc-6979`: Support for nonce generation according to RFC-9381 section 5.4.2.1.
+//! - `test-vectors`: Deterministic ring-vrf proof. Useful for reproducible test vectors generation.
+//!
+//! ### Curves
+//!
+//! - `ed25519`
+//! - `jubjub`
+//! - `bandersnatch`
+//! - `baby-jubjub`
+//! - `secp256r1`
+//!
+//! ### Arkworks optimizations
+//!
+//! - `parallel`: Parallel execution where worth using `rayon`.
+//! - `asm`: Assembly implementation of some low level operations.
+//!
+//! ## License
+//!
+//! Distributed under the [MIT License](./LICENSE).
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![deny(unsafe_code)]
 
-use zeroize::Zeroize;
-
 use ark_ec::{AffineRepr, CurveGroup};
 use ark_ff::{One, PrimeField, Zero};
 use ark_serialize::{CanonicalDeserialize, CanonicalSerialize};
 use ark_std::vec::Vec;
 
 use digest::Digest;
+use zeroize::Zeroize;
 
 pub mod codec;
 pub mod ietf;
@@ -37,8 +145,9 @@ pub mod ring;
 #[cfg(test)]
 mod testing;
 
-// Re-export stuff that may be useful downstream.
-#[doc(hidden)]
+use codec::Codec;
+
+/// Re-export stuff that may be useful downstream.
 pub mod reexports {
     pub use ark_ec;
     pub use ark_ff;
@@ -47,15 +156,13 @@ pub mod reexports {
 }
 
 pub type AffinePoint<S> = <S as Suite>::Affine;
-
 pub type BaseField<S> = <AffinePoint<S> as AffineRepr>::BaseField;
 pub type ScalarField<S> = <AffinePoint<S> as AffineRepr>::ScalarField;
 pub type CurveConfig<S> = <AffinePoint<S> as AffineRepr>::Config;
 
 pub type HashOutput<S> = digest::Output<<S as Suite>::Hasher>;
 
-pub use codec::Codec;
-
+/// Overarching errors.
 #[derive(Debug)]
 pub enum Error {
     /// Verification error
@@ -242,7 +349,7 @@ impl<S: Suite> Secret<S> {
 
     /// Get the VRF output point relative to input.
     pub fn output(&self, input: Input<S>) -> Output<S> {
-        Output((input.0 * self.scalar).into_affine())
+        Output(smul!(input.0, self.scalar).into_affine())
     }
 }
 
@@ -289,6 +396,7 @@ impl<S: Suite> Output<S> {
     }
 }
 
+/// Type aliases for the given suite.
 #[macro_export]
 macro_rules! suite_types {
     ($suite:ident) => {

src/pedersen.rs

@@ -1,3 +1,5 @@
+//! Pedersen VRF
+
 use crate::ietf::IetfSuite;
 use crate::*;
 
@@ -89,12 +91,17 @@ impl<S: PedersenSuite> Prover<S> for Secret<S> {
         let kb = S::nonce(&blinding, input);
 
         // Yb = x*G + b*B
-        let pk_com = (S::generator() * self.scalar + S::BLINDING_BASE * blinding).into_affine();
+        let xg = smul!(S::generator(), self.scalar);
+        let bb = smul!(S::BLINDING_BASE, blinding);
+        let pk_com = (xg + bb).into_affine();
 
         // R = k*G + kb*B
-        let r = (S::generator() * k + S::BLINDING_BASE * kb).into_affine();
+        let kg = smul!(S::generator(), k);
+        let kbb = smul!(S::BLINDING_BASE, kb);
+        let r = (kg + kbb).into_affine();
+
         // Ok = k*I
-        let ok = (input.0 * k).into_affine();
+        let ok = smul!(input.0, k).into_affine();
 
         // c = Hash(Yb, I, O, R, Ok, ad)
         let c = S::challenge(&[&pk_com, &input.0, &output.0, &r, &ok], ad.as_ref());

src/ring.rs

@@ -1,3 +1,6 @@
+//! Ring VRF.
+//!
+//! This module is gated by the `ring` feature.
 use crate::*;
 use ark_ec::{
     pairing::Pairing,
@@ -543,7 +546,7 @@ where
     }
 }
 
-/// Define type aliases for the given ring suite.
+/// Type aliases for the given ring suite.
 #[macro_export]
 macro_rules! ring_suite_types {
     ($suite:ident) => {
@@ -734,7 +737,6 @@ pub(crate) mod testing {
         while !pks.is_empty() {
             let chunk_len = 1 + random_val::<usize>(Some(rng)) % 5;
             let chunk = pks.drain(..pks.len().min(chunk_len)).collect::<Vec<_>>();
-            println!("Appending {} items", chunk.len());
             vk_builder.append(&chunk[..], &loader).unwrap();
             assert_eq!(vk_builder.free_slots(), pks.len());
         }

src/suites/baby_jubjub.rs

@@ -4,7 +4,7 @@
 //!
 //! * `suite_string` = b"Baby-JubJub_SHA-512_TAI".
 //!
-//! - The EC group is the prime subgroup of the Baby-JubJub elliptic curve
+//! - The EC group **G** is the prime subgroup of the Baby-JubJub elliptic curve
 //!   as defined by <https://github.com/barryWhiteHat/baby_jubjub>.
 //!   For this group, `fLen` = `qLen` = $32$ and `cofactor` = $8$.
 //!
@@ -27,7 +27,7 @@
 //! * The string_to_int function decodes from the 32 bytes little endian
 //!   representation.
 //!
-//! * The point_to_string function converts a point in <G> to an octet
+//! * The point_to_string function converts a point in **G** to an octet
 //!   string using compressed form. The y coordinate is encoded using
 //!   int_to_string function and the most significant bit of the last
 //!   octet is used to keep track of the x's sign. This implies that