Merge pull request #4 from Mactherobot/dec-29

Finish Preliminaries

sdith/Cargo.toml

@@ -4,7 +4,7 @@ description = "SDitH Signature Scheme Protocol from NIST Post-Quantum Cryptograp
 version = "0.0.0"
 edition = "2021"
 resolver = "2"
-default-run = "cli"                                                                                                                       # Default run the cli
+default-run = "sdith"                                                                                                                       # Default run the cli
 
 # We manually specify targets below
 autobenches = false
@@ -50,7 +50,7 @@ bench = false       # Prevents benchmarks from running src/lib.rs tests
 doctest = false     # Prevents doctests from src/lib.rs
 
 [[bin]]
-name = "cli"
+name = "sdith"
 path = "src/bin/cli/mod.rs"
 test = false                # Prevents tests from cli
 bench = false               # Prevents benchmarks from cli
@@ -60,6 +60,7 @@ name = "profiling_sign"
 path = "src/bin/profiling/sign.rs"
 test = false                       # Prevents tests from profiling
 bench = false                      # Prevents benchmarks from profiling
+doc = false
 
 [[bench]]
 name = "benchmark"

sdith/src/bin/cli/mod.rs

@@ -1,8 +1,31 @@
+//! # SDitH Protocol Command Line Interface
+//! 
+//! Usage: sdith [COMMAND]
+//! 
+//! Commands:
+//!   keygen      SDitH signature protocol -- key generation
+//!   sign        SDitH signature protocol -- signing
+//!   verify      SDitH signature protocol -- verification
+//!   parameters  SDitH signature protocol -- print parameters
+//!   help        Print this message or the help of the given subcommand(s)
+//! 
+//! Options:
+//!   -h, --help     Print help
+//!   -V, --version  Print version
+//! 
+//! ## Build the CLI
+//! 
+//! The CLI can be built with the following command:
+//! 
+//! ```
+//! cargo build --release --bin sdith --features [category]
+//! ```
+
 use clap::{CommandFactory, Parser};
 use cli::Commands;
 use colored::Colorize as _;
 
-pub mod cli;
+mod cli;
 
 fn main() {
     let cli = cli::Cli::parse();

sdith/src/constants/mod.rs

@@ -3,7 +3,6 @@
 //! The SDitH Signature Scheme comes with three categories of parameters according to the NIST post-quantum cryptography standardization process.
 //!
 //! The constants are generated using the build.rs script and exposed through the [`params`] module.
-//! Furthermore, the [`precomputed`] module contains precomputed values for the SDitH Signature Scheme.
 //!
 //! The [`types`] module contains the types used in the SDitH Signature Scheme like
 //! [`crate::constants::types::Hash`] and [`crate::constants::types::Seed`].

sdith/src/lib.rs

@@ -8,6 +8,14 @@
 //! a given shared input corresponds to the solution of a syndrome decoding instance
 //! By applying the MPC-in-the-Head paradigm, this protocol is turned into a zero-knowledge proof
 //! of knowledge for the syndrome decoding problem that is then transformed into a signature scheme using the Fiat-Shamir heuristic.
+//! 
+//! Find information about
+//! 
+//! - The protocol endpoints in the [`keygen`] and [`signature`] modules.
+//! - The [`subroutines`] module for the subroutines used in the SDitH protocol.
+//! - The [`constants`] module for the constants used in the SDitH protocol.
+//! - The [`utils`] module for utility functions.
+//! - The [`witness`] module for the witness generation in itself a subroutine of the [`keygen`] module.
 
 // Allocator features
 #[cfg_attr(feature = "jemalloc", global_allocator)]

sdith/src/signature/mod.rs

@@ -1,6 +1,13 @@
 //! # Signature
 //!
 //! This module contains the implementation of the signature struct and its methods.
+//! 
+//! Contains the [`Signature`] struct which holds endpoints
+//! - Signing: [`Signature::sign_message`] 
+//! - Verifying: [`Signature::verify_signature`] functions.
+//! 
+//! Check out the [`crate::subroutines`] module for the subroutines used in the signature scheme.
+//! Check out the [`crate::keygen`] module for the key generation.
 
 mod sign;
 mod verify;

sdith/src/subroutines/arith/gf256/mod.rs

@@ -2,7 +2,7 @@
 //!
 //! The field is an implementation of Rijndael's finite field with 256 elements.
 //!
-//! This module supplies [`crate::arith::FieldArith`] trait implementations for the field elements in GF(256).
+//! This module supplies [`crate::subroutines::arith::FieldArith`] trait implementations for the field elements in GF(256).
 //!
 //! See implementation for [`u8`](gf256_arith) and [`FPoint`](gf256_ext::FPoint)
 

sdith/src/subroutines/challenge.rs

@@ -3,7 +3,7 @@
 //! MPCitH challenge generation and precomputed values
 //!
 //! - MPCChallenge: pair (r, e) ∈ F_point^t, (F_point^t)^d
-//! - View opening challenge: I ∈ [N] for |I| = l
+//! - View opening challenge: I ∈ \[N\] for |I| = l
 
 use core::fmt;
 use std::fmt::Formatter;

sdith/src/subroutines/merkle_tree.rs

@@ -4,7 +4,7 @@
 //! This scheme is used by the signature scheme to commit to the shares of the parties.
 //!
 //! The tree is constructed from a list of commitments, where each leaf is a commitment.
-//! Parents are calculated by hashing the concatenation of the left and right children along with a [prefix](HASH_PREFIX_MERKLE_TREE).
+//! Parents are calculated by hashing the concatenation of the left and right children along with a prefix.
 //! The root of the tree is then sent as the final commitment.
 //!
 //! To open a commitment, the prover sends the commitment along with the hashed path from the leaf to the root.

sdith/src/subroutines/mod.rs

@@ -7,7 +7,6 @@
 //! - [`merkle_tree`]: Contains the functions for generating and verifying Merkle Trees Commitment Scheme.
 //! - [`prg`]: Contains the functions for generating Pseudo Random Generators.
 //! - [`mpc`]: Contains the functions for the Multi-Party Simulationl.
-//! - [`marshalling`]: Contains the trait and test function for serializing and deserializing data.
 
 pub mod arith;
 pub mod commitments;

sdith/src/subroutines/prg/mod.rs

@@ -6,8 +6,8 @@
 //! implemented in the [`hashing`] module.
 //!
 //! ## XOF
-//! Extendable Output Functions (XOFs) are used to generate pseudorandom values in the fields [F_q](crate::arith::gf256::FieldArith)
-//! and [F_q^\eta](crate::arith::gf256::gf256_ext::FPoint).. The XOFs are implemented in the [`xof`] module.
+//! Extendable Output Functions (XOFs) are used to generate pseudorandom values in the fields [F_q](crate::subroutines::arith::FieldArith)
+//! and [F_q^\eta](crate::subroutines::arith::gf256::gf256_ext::FPoint).. The XOFs are implemented in the [`xof`] module.
 
 pub mod hashing;
 pub mod xof;
@@ -56,7 +56,7 @@ impl PRG {
         }
     }
 
-    /// Sample non-zero random values in the field [F_q](crate::arith::gf256::FieldArith)
+    /// Sample non-zero random values in the field [F_q](crate::subroutines::arith::FieldArith)
     pub fn sample_field_fq_non_zero(&mut self, output: &mut [u8]) {
         for i in 0..output.len() {
             self.sample_field_fq_elements(&mut output[i..i + 1]);
@@ -66,7 +66,7 @@ impl PRG {
         }
     }
 
-    /// Sample **distinct** random values in the field [F_q](crate::arith::gf256::FieldArith)
+    /// Sample **distinct** random values in the field [F_q](crate::subroutines::arith::FieldArith)
     ///
     /// The output length must be less than 256
     pub fn sample_field_fq_distinct(&mut self, output: &mut [u8]) -> Result<(), String> {
@@ -90,7 +90,7 @@ impl PRG {
         Ok(())
     }
 
-    /// Sample a random [`Vec`] in the field [F_q](crate::arith::gf256::FieldArith)
+    /// Sample a random [`Vec`] in the field [F_q](crate::subroutines::arith::FieldArith)
     pub fn sample_field_fq_elements_vec(&mut self, n: usize) -> Vec<u8> {
         let mut f = vec![0u8; n];
         self.xof.squeeze(&mut f);

sdith/src/subroutines/prg/xof.rs

@@ -1,7 +1,7 @@
 //! # Extendable output function (XOF).
 //!
 //! The pseudorandomness in SD-in-the-Head is generated through an extendable output hash function (XOF).
-//! For example, we can easily generate an array of random values in [F_q](crate::arith::gf256::FieldArith) by
+//! For example, we can easily generate an array of random values in [F_q](crate::subroutines::arith::FieldArith) by
 //! sampling a random hash `n` byte hash output and interpreting it as an array of field elements.
 
 #[cfg(not(feature = "xof_blake3"))]

sdith/src/utils/mod.rs

@@ -1,7 +1,6 @@
 //! # Utilities
 //! This module contains the utilities used in the SDitH protocol.
 //! 
-//! - [`iterator`]: Contains the functions for iterating over the data. Uses feature flags to enable parallel iterations
 //! - [`marshalling`]: Contains the trait and test function for serializing and deserializing data.
 
 pub(crate) mod iterator;