Write docs

Author: survived

cggmp21/src/lib.rs

@@ -16,6 +16,7 @@ pub mod keygen;
 pub mod progress;
 pub mod security_level;
 pub mod signing;
+pub mod supported_curves;
 pub mod trusted_dealer;
 mod utils;
 

cggmp21/src/progress.rs

@@ -1,57 +1,115 @@
 //! Traces progress of protocol execution
+//!
+//! Provides [`Tracer`] trait that can be used to trace progress of ongoing MPC protocol execution.
+//! For instance, it can be implemented to report progress to the end user.
+//!
+//! Out of box, there's [`PerfProfiler`] which can be used to bechmark a protocol.
+//!
+//! ## Usage example
+//! Provide tracer to the protocol builder and obtain results after protocol is completed:
+//!
+//! ```rust,no_run
+//! # use cggmp21::key_share::{Valid, KeyShare};
+//! # type E = cggmp21::supported_curves::Secp256r1;
+//! # type L = cggmp21::security_level::ReasonablySecure;
+//! # fn load_key_share() -> Result<Valid<KeyShare<E, L>>, std::convert::Infallible> { unimplemented!() }
+//! # async fn connect_to_network<M>() -> Result<round_based::MpcParty<M, round_based::simulation::MockedDelivery<M>>, std::convert::Infallible> { unimplemented!() }
+//! # async fn doc() -> Result<(), Box<dyn std::error::Error>> {
+//! use cggmp21::progress::PerfProfiler;
+//!
+//! let mut tracer = PerfProfiler::new();
+//!
+//! let party = connect_to_network().await?;
+//! let key_share = load_key_share()?;
+//! cggmp21::signing(&key_share)
+//!     .set_progress_tracer(&mut tracer)
+//!     .generate_presignature(&mut rand::rngs::OsRng, party)
+//!     .await?;
+//! # Ok(()) }
+//!```
 
 use std::fmt;
 use std::time::{Duration, Instant};
 
 use thiserror::Error;
 
+/// Traces progress of protocol execution
+///
+/// See [module level documentation](self) for more details
 pub trait Tracer: Send + Sync {
+    /// Traces occurred event
     fn trace_event(&mut self, event: Event);
 
+    /// Traces [`Event::ProtocolBegins`] event
     fn protocol_begins(&mut self) {
         self.trace_event(Event::ProtocolBegins)
     }
+    /// Traces [`Event::RoundBegins`] event
     fn round_begins(&mut self) {
         self.trace_event(Event::RoundBegins { name: None })
     }
+    /// Traces [`Event::RoundBegins`] event
     fn named_round_begins(&mut self, round_name: &'static str) {
         self.trace_event(Event::RoundBegins {
             name: Some(round_name),
         })
     }
+    /// Traces [`Event::Stage`] event
     fn stage(&mut self, stage: &'static str) {
         self.trace_event(Event::Stage { name: stage })
     }
+    /// Traces [`Event::ReceiveMsgs`] event
     fn receive_msgs(&mut self) {
         self.trace_event(Event::ReceiveMsgs)
     }
+    /// Traces [`Event::MsgsReceived`] event
     fn msgs_received(&mut self) {
         self.trace_event(Event::MsgsReceived)
     }
+    /// Traces [`Event::SendMsg`] event
     fn send_msg(&mut self) {
         self.trace_event(Event::SendMsg)
     }
+    /// Traces [`Event::MsgSent`] event
     fn msg_sent(&mut self) {
         self.trace_event(Event::MsgSent)
     }
+    /// Traces [`Event::ProtocolEnds`] event
     fn protocol_ends(&mut self) {
         self.trace_event(Event::ProtocolEnds)
     }
 }
 
+/// Event occurred during the protocol execution
 #[derive(Debug, PartialEq, Eq, Copy, Clone)]
 pub enum Event {
+    /// Protocol begins
+    ///
+    /// This event is always emitted before any other events
     ProtocolBegins,
 
-    RoundBegins { name: Option<&'static str> },
-    Stage { name: &'static str },
-
+    /// Round begins
+    RoundBegins {
+        /// Optional name of the round
+        name: Option<&'static str>,
+    },
+    /// Stage begins
+    Stage {
+        /// Name of the stage
+        name: &'static str,
+    },
+
+    /// Protocol waits for some messages to be received
     ReceiveMsgs,
+    /// Protocol received messages, round continues
     MsgsReceived,
 
+    /// Protocol starts sending a message
     SendMsg,
+    /// Protocol sent a message, round continues
     MsgSent,
 
+    /// Protocol completed
     ProtocolEnds,
 }
 
@@ -78,6 +136,11 @@ impl<T: Tracer> Tracer for Option<T> {
     }
 }
 
+/// Profiles performance of the protocol
+///
+/// Implements [`Tracer`] trait so it can be embedded into protocol execution. `PerfProfiler` keeps track of time
+/// passed between each step of protocol. After protocol is completed, you can obtain a [`PerfReport`] via
+/// [`.get_report()`](PerfProfiler::get_report) method that contains all the measurements.
 pub struct PerfProfiler {
     last_timestamp: Option<Instant>,
     ongoing_stage: Option<usize>,
@@ -86,29 +149,43 @@ pub struct PerfProfiler {
     error: Option<ProfileError>,
 }
 
+/// Performance report generated by [`PerfProfiler`]
 #[derive(Debug, Clone)]
 pub struct PerfReport {
+    /// Duration of setup phase (time after protocol began and before first round started)
     pub setup: Duration,
+    /// Stages of setup phase
     pub setup_stages: Vec<StageDuration>,
+    /// Performance report for each round
     pub rounds: Vec<RoundDuration>,
     display_io: bool,
 }
 
+/// Performance of specific round (part of [`PerfReport`])
 #[derive(Debug, Clone)]
 pub struct RoundDuration {
+    /// Round name (if provided)
     pub round_name: Option<&'static str>,
+    /// Stages of the round
     pub stages: Vec<StageDuration>,
+    /// Total duration of pure computation performed during the round
     pub computation: Duration,
+    /// Total time we spent during this round on sending messages
     pub sending: Duration,
+    /// Total time we spent during this round on receiving messages
     pub receiving: Duration,
 }
 
+/// Performance of specific stage (part of [`PerfReport`])
 #[derive(Debug, Clone)]
 pub struct StageDuration {
+    /// Stage name
     pub name: &'static str,
+    /// Duration of the stage
     pub duration: Duration,
 }
 
+/// Protocol profiling resulted into error
 #[derive(Debug, Error, Clone)]
 #[error("profiler failed to trace protocol: it behaved unexpectedly")]
 pub struct ProfileError(
@@ -118,13 +195,11 @@ pub struct ProfileError(
 );
 
 #[derive(Debug, Error, Clone)]
-pub enum ErrorReason {
+enum ErrorReason {
     #[error("protocol has never began")]
     ProtocolNeverBegan,
     #[error("tracing stage or sending/receiving message but round never began")]
     RoundNeverBegan,
-    #[error("bug: unreachable condition happened")]
-    Unreachable,
     #[error("stage is ongoing, but it can't be finished with that event: {event:?}")]
     CantFinishStage { event: Event },
 }
@@ -140,6 +215,7 @@ impl Tracer for PerfProfiler {
 }
 
 impl PerfProfiler {
+    /// Constructs new [`PerfProfiler`]
     pub fn new() -> Self {
         Self {
             last_timestamp: None,
@@ -155,6 +231,9 @@ impl PerfProfiler {
         }
     }
 
+    /// Obtains a report
+    ///
+    /// Returns error if protocol behaved unexpectedly
     pub fn get_report(&self) -> Result<PerfReport, ProfileError> {
         if let Some(err) = self.error.clone() {
             Err(err)

cggmp21/src/security_level.rs

@@ -1,13 +1,13 @@
 //! Security level of CGGMP protocol
 //!
-//! Security level is measured in bits and defined as $\kappa$ and $\varepsilon$ in paper. Higher
-//! security level gives more security but makes protocol execution slower.
+//! Security level is defined as set of parameters in the CGGMP paper. Higher security level gives more
+//! security but makes protocol execution slower.
 //!
-//! We provide two predefined security levels: [ReasonablySecure], which should be used in production,
-//! and [DevelopmentOnly], which is insecure but fast and can be used for testing.
+//! We provide a predefined [ReasonablySecure] security level which is recommended to use for most use-cases.
 //!
 //! You can define your own security level using macro [define_security_level]. Be sure that you properly
-//! analyzed the paper and you understand implications.
+//! analyzed the CGGMP paper and you understand implications. Inconsistent security level may cause unexpected
+//! unverbose runtime error or reduced security of the protocol.
 
 use paillier_zk::libpaillier::unknown_order::BigNumber;
 
@@ -90,7 +90,7 @@ pub mod _internal {
 ///
 /// ## Example
 ///
-/// Let's define security level corresponding to $\kappa=1024$, $\varepsilon=128$, $\ell = \ell' = 1024$,
+/// This code defines security level corresponding to $\kappa=1024$, $\varepsilon=128$, $\ell = \ell' = 1024$,
 /// $m = 50$, and $q = 2^{48}-1$:
 /// ```rust
 /// use cggmp21::security_level::define_security_level;

cggmp21/src/supported_curves.rs

@@ -0,0 +1,31 @@
+//! Curves supported by this crate
+//!
+//! This crate re-exports curves that are checked to work correctly with our CGGMP implementation.
+//! Generally, this crate can work with any curve as long as it satisfies constraints (check out
+//! [`SigningBuilder`](crate::signing::SigningBuilder) generic constraints), but it might have
+//! unexpected consequences: for instance, [default security level](crate::security_level::ReasonablySecure)
+//! might not be compatible with another curve, which might result into unexpected runtime error or
+//! reduced security of the protocol.
+
+pub use generic_ec::curves::Secp256r1;
+pub use generic_ec::Curve;
+
+#[cfg(test)]
+#[allow(dead_code)]
+mod check_compatibility {
+    use generic_ec::{
+        coords::AlwaysHasAffineX, hash_to_curve::FromHash, Curve, NonZero, Point, Scalar,
+    };
+
+    fn curve_is_compatible<E: Curve>()
+    where
+        Scalar<E>: FromHash,
+        NonZero<Point<E>>: AlwaysHasAffineX<E>,
+    {
+    }
+
+    fn supported_curves_are_compatible() {
+        // curve_is_compatible::<super::Secp256k1>(); // secp256k1 is not yet supported
+        curve_is_compatible::<super::Secp256r1>();
+    }
+}