Resolve half of #67 (Part 1/2) (#93)

* current progress

* link to relevant issue

* crate name edit

* Flat the docs entities

* meta information

* Update the crate name in `tests`

* current progress

rust-arkworks/Cargo.toml

@@ -1,18 +1,22 @@
 [package]
-name = "sig"
-version = "0.1.0"
+name = "plume_arkworks"
+version = "0.0.1"
 edition = "2021"
+license = "MIT"
+description = "Implementation of PLUME: nullifier friendly signature scheme on ECDSA; using the `arkworks-rs` libraries"
+repository = "https://github.com/plume-sig/zk-nullifier-sig/"
+categories = ["cryptography", "cryptography::cryptocurrencies"]
+keywords = ["nullifier", "zero-knowledge", "ECDSA", "PLUME"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
 ark-ec = "~0.3.0"
-ark-ff = "0.3.0"
-ark-std = "0.3.0"
-ark-serialize = "0.3.0"
-ark-serialize-derive = "0.3.0"
-thiserror = "1.0.30"
-secp256k1 = { git = "https://github.com/geometryresearch/ark-secp256k1.git" }
+ark-ff = "~0.3.0"
+ark-std = "~0.3.0"
+ark-serialize = "~0.3.0"
+ark-serialize-derive = "~0.3.0"
+secp256k1 = { git = "https://github.com/geometryresearch/ark-secp256k1.git", version = "0.1.0" }
 rand_core = { version = "0.6", default-features = false, features = [
     "getrandom",
 ] }

rust-arkworks/README.MD

@@ -0,0 +1,3 @@
+https://github.com/plume-sig/zk-nullifier-sig/blob/main/README.md
+# HAZMAT
+Please note that until `v0.1.0` this is very much a preview crate which lets you have some preliminary feel of the structure and the reference implementation approach.

rust-arkworks/src/error.rs

@@ -3,7 +3,7 @@
 
 // use thiserror::Error;
 
-/// This is an error that could occur when running a cryptograhic primitive
+// /// This is an error that could occur when running a cryptograhic primitive
 // #[derive(Error, Debug, PartialEq)]
 // pub enum CryptoError {
 // #[error("Cannot hash to curve")]
@@ -14,13 +14,18 @@
 // }
 
 // Let's outline what errors will be in `~0.4.0`
+/// It's an interim `enum` between legacy definition of the errors and prospective which will be relying on [`ark_ec::hashing::HashToCurveError`]. 
 #[derive(Debug, Clone)]
 pub enum HashToCurveError {
+    /// Mimics the `ark_ec::hashing::HashToCurveError` enum
     UnsupportedCurveError(String),
+    /// Mimics the `ark_ec::hashing::HashToCurveError` enum
     MapToCurveError(String),
     /* let's add two more items to absorb everything
     in `crate::hash_to_curve` which is
     subject to deprecation */
+    /// Absorbs any legacy error in [`mod@crate::hash_to_curve`]. They will be deprecated with upgrade to `~0.4.0`.
     Legacy,
+    /// A special case for a reference function. It will be moved to <./examples> with the upgrade to `~0.4.0`.
     ReferenceTryAndIncrement,
 }

rust-arkworks/src/lib.rs

@@ -1,10 +1,26 @@
-use crate::error::HashToCurveError;
+/// This crate provides the PLUME signature scheme.
+///
+/// See <https://blog.aayushg.com/nullifier> for more information.
+/// 
+/// Find RustCrypto crate as `plume_rustcrypto`.
+
+pub use crate::error::HashToCurveError;
 use crate::hash_to_curve::hash_to_curve;
-use ark_ec::short_weierstrass_jacobian::GroupAffine;
-use ark_ec::{models::SWModelParameters, AffineCurve, ProjectiveCurve};
+
+/// Re-exports the `GroupAffine` and `SWModelParameters` types from the `ark_ec` crate.
+///
+/// `GroupAffine` represents an affine point on a short Weierstrass elliptic curve.
+/// `SWModelParameters` contains the parameters defining a short Weierstrass curve.
+pub use ark_ec::{models::SWModelParameters, short_weierstrass_jacobian::GroupAffine};
+/// Re-exports the `Rng` trait from the `rand` crate in `ark_std`.
+///
+/// `Rng` provides methods for generating random values.
+pub use ark_std::rand::Rng;
+
+use ark_ec::{AffineCurve, ProjectiveCurve};
 use ark_ff::PrimeField;
 use ark_serialize::{CanonicalDeserialize, CanonicalSerialize, Read, SerializationError, Write};
-use ark_std::{rand::Rng, UniformRand};
+use ark_std::UniformRand;
 use secp256k1::sec1::Sec1EncodePoint;
 use sha2::digest::Output;
 use sha2::{Digest, Sha256};
@@ -14,11 +30,15 @@ mod hash_to_curve;
 
 const EXPECT_MSG_DECODE: &str = "the value decoded have been generated by a function which is improbable to output a malformed hexstring (still a place for refactoring)";
 
+/// An `enum` representing the variant of the PLUME protocol.
 pub enum PlumeVersion {
     V1,
     V2,
 }
 
+/// Converts an affine point on the curve to the byte representation.
+///
+/// Serializes the affine point to its SEC1 encoding and returns the raw bytes.
 pub fn affine_to_bytes<P: SWModelParameters>(point: &GroupAffine<P>) -> Vec<u8> {
     hex::decode(point.to_encoded_point(true))
         .expect(EXPECT_MSG_DECODE)
@@ -72,45 +92,58 @@ fn compute_c_v2<P: SWModelParameters>(
     Sha256::digest(c_preimage_vec.as_slice())
 }
 
+/// A struct containing parameters for the SW model, including the generator point `g_point`.
+/// This struct implements traits for (de)serialization.
 #[derive(
     Copy,
     Clone,
     ark_serialize_derive::CanonicalSerialize,
     ark_serialize_derive::CanonicalDeserialize,
 )]
 pub struct Parameters<P: SWModelParameters> {
+    /// The generator point for the SW model parameters.
     pub g_point: GroupAffine<P>,
 }
 
+/// A struct containing the PLUME signature data
 #[derive(
     Copy,
     Clone,
     ark_serialize_derive::CanonicalSerialize,
     ark_serialize_derive::CanonicalDeserialize,
 )]
 pub struct PlumeSignature<P: SWModelParameters> {
+    /// The hash-to-curve output multiplied by the random `r`.  
     pub hashed_to_curve_r: GroupAffine<P>,
+    /// The randomness `r` represented as the curve point.
     pub r_point: GroupAffine<P>,
     pub s: P::ScalarField,
     pub c: P::ScalarField,
+    /// The nullifier.
     pub nullifier: GroupAffine<P>,
 }
 
 // These aliases should be gone in #88 . If they won't TODO pay attention to the warning about `trait` boundaries being not checked for aliases
 //      also not enforcing trait bounds can impact PublicKey -- it's better to find appropriate upstream type
-type Message<'a> = &'a [u8];
-type PublicKey<P: SWModelParameters> = GroupAffine<P>;
-type SecretKeyMaterial<P: SWModelParameters> = P::ScalarField;
+
+/// A type alias for a byte slice reference, used for representing the message.
+pub type Message<'a> = &'a [u8];
+/// The public key.
+pub type PublicKey<P: SWModelParameters> = GroupAffine<P>;
+/// The scalar field element representing the secret key.
+pub type SecretKeyMaterial<P: SWModelParameters> = P::ScalarField;
 
 impl<P: SWModelParameters> PlumeSignature<P> {
     /// Generate the public key and a private key.
-    fn keygen(pp: &Parameters<P>, rng: &mut impl Rng) -> (PublicKey<P>, SecretKeyMaterial<P>) {
+    /// # HAZMAT
+    /// No measures yet taken for the [`SecretKeyMaterial`] protection
+    pub fn keygen(pp: &Parameters<P>, rng: &mut impl Rng) -> (PublicKey<P>, SecretKeyMaterial<P>) {
         let secret_key = SecretKeyMaterial::<P>::rand(rng);
         let public_key = pp.g_point.mul(secret_key).into();
         (public_key, secret_key)
     }
 
-    /// Sign a message using a specified r value
+    /// Sign a message using the specified `r` value
     fn sign_with_r(
         pp: &Parameters<P>,
         keypair: (&PublicKey<P>, &SecretKeyMaterial<P>),
@@ -174,6 +207,16 @@ impl<P: SWModelParameters> PlumeSignature<P> {
         Self::sign_with_r(pp, keypair, message, r_scalar, version)
     }
 
+    /// Verifies a PLUME signature.
+    /// Returns `true` if the signature is valid, `false` otherwise.
+    ///
+    /// Computes the curve points and scalars needed for verification from the
+    /// signature parameters. Then performs the verification steps:
+    /// - Confirm g^s * pk^-c = g^r
+    /// - Confirm h^s * nul^-c = z
+    /// - Confirm c = c'
+    ///
+    /// Rejects if any check fails.
     fn verify_non_zk(
         self,
         pp: &Parameters<P>,

rust-k256/Cargo.toml

@@ -1,7 +1,12 @@
 [package]
-name = "zk-nullifier"
+name = "plume_rustcrypto"
 version = "0.1.0"
 edition = "2021"
+license = "MIT"
+description = "Implementation of PLUME: nullifier friendly signature scheme on ECDSA; using the k256 library"
+repository = "https://github.com/plume-sig/zk-nullifier-sig/"
+categories = ["cryptography", "cryptography::cryptocurrencies"]
+keywords = ["nullifier", "zero-knowledge", "ECDSA", "PLUME"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 

rust-k256/README.MD

@@ -0,0 +1 @@
+https://github.com/plume-sig/zk-nullifier-sig/blob/main/README.md