WIP Doc improvements

README.md

@@ -1,9 +1,18 @@
-# SEEC
+# SEEC Executes Enormous Circuits
 
-This framework implements secure 2-party secret-sharing based multi party computation protocols. Currently, we implement the Boolean and arithmetic versions of GMW87 with multiplication triple preprocessing. Additionally, we implement the Boolean part of the ABY2.0 protocol. 
+This framework implements secure 2-party secret-sharing-based multi party computation protocols. Currently, we implement the Boolean and arithmetic versions of GMW87 with multiplication triple preprocessing. Additionally, we implement the Boolean part of the ABY2.0 protocol.
 
-## Development
+## Secure Multi-Party Computation
+In secure multi-party computation (MPC), there are n parties, each with their private input x_i. Given a public function f(x_1, ..., x_n), the parties execute a protocol π that correctly and securely realizes the functionality f. In other words, at the end of the protocol, the parties know the output of f, but have no information about the input of the other parties other than what is revealed by the output itself. Currently, SEEC is limited to the n = 2 party case, also known as secure two-party computation. We hope to extend this in the future to n parties.
+
+### Security
+The two most prevalent security models are
+- semi-honest security, where an attacker can corrupt parties, but they follow the protocol as specified.
+- malicious security, where corrupted parties can arbitrarily deviate from the protocol.
 
+SEEC currently only implements semi-honestly secure protocols (GMW, ABY2.0). 
+
+## Development
 ### Installing Rust
 
 The project is implemented in the [Rust](https://www.rust-lang.org/) programming language. To compile it, the latest stable toolchain is needed (older toolchains might work but are not guaranteed). The recommended way to install it, is via the toolchain manager [rustup](https://rustup.rs/).

crates/seec/examples/simple.rs

@@ -12,14 +12,14 @@ use bitvec::prelude::*;
 use tokio::time::sleep;
 use tracing_subscriber::EnvFilter;
 
+use seec::channel::sub_channels_for;
 use seec::circuit::{dyn_layers::Circuit, DefaultIdx, ExecutableCircuit};
 use seec::executor::{Executor, Input, Message};
 use seec::mul_triple::boolean::insecure_provider::InsecureMTProvider;
 use seec::mul_triple::MTProvider;
 use seec::protocols::boolean_gmw::BooleanGmw;
 use seec::secret::inputs;
 use seec::CircuitBuilder;
-use seec_channel::sub_channels_for;
 
 fn build_circuit() {
     // The `inputs` method is a convenience method to create n input gates for the circuit.

crates/seec/src/bench.rs

@@ -1,3 +1,9 @@
+//! Insecure Benchmarking API - Do not use in Production!
+//!
+//! The [`BenchParty`] API provides an easy way of benchmarking an MPC application
+//! or protocol implemented in SEEC. An example of its usage is e.g. located in the
+//! `crates/seec/examples/bristol.rs` binary.
+
 use crate::circuit::{ExecutableCircuit, GateIdx};
 use crate::executor::{Executor, Input, Message};
 use crate::mul_triple::storage::MTStorage;

crates/seec/src/lib.rs

@@ -1,10 +1,54 @@
+//! # SEEC Executes Enormous Circuits
+//!
+//! This framework implements secure 2-party secret-sharing-based multi party computation protocols.
+//! Currently, we implement the Boolean and arithmetic versions of GMW87 with multiplication triple preprocessing.
+//! Additionally, we implement the Boolean part of the ABY2.0 protocol.
+//!
+//! ## Secure Multi-Party Computation
+//! In secure multi-party computation (MPC), there are n parties, each with their private input x_i.
+//! Given a public function f(x_1, ..., x_n), the parties execute a protocol π that correctly and
+//! securely realizes the functionality f. In other words, at the end of the protocol, the parties know
+//! the output of f, but have no information about the input of the other parties other than what is revealed
+//! by the output itself. Currently, SEEC is limited to the n = 2 party case, also known as secure
+//! two-party computation. We hope to extend this in the future to n parties.
+//!
+//! ### Security
+//! The two most prevalent security models are
+//! - semi-honest security, where an attacker can corrupt parties, but they follow the protocol as specified.
+//! - malicious security, where corrupted parties can arbitrarily deviate from the protocol.
+//!
+//! SEEC currently only implements semi-honestly secure protocols (GMW, ABY2.0).
+//!
+//! ## Using SEEC
+//! To use SEEC, you need a recent stable Rust toolchain (nightly on ARM[^nightly]). The easiest way to install Rust
+//! is via the official toolchain installer [rustup](https://rustup.rs/).
+//!
+//! Create a new Rust project using cargo `cargo new --bin seec-test`, and add SEEC as a dependency to your
+//! `Cargo.toml`
+//! ```shell
+//! // seec-test/Cargo.toml
+//! [dependencies]
+//! seec = { git = "ssh://[email protected]/encrypto/code/rnieminen/rust-framework.git" }
+//! ```
+//! (Note: currently SEEC is only available as a private git repository. Make sure that your
+//! [ssh-agent](https://linux.die.net/man/1/ssh-agent)) is started. More information [here](https://doc.rust-lang.org/cargo/appendix/git-authentication.html)
+//!
+//! The following annotated example of using SEEC is also located at `crates/seec/examples/simple.rs`.
+//! You can run it using `cargo run --example simple`.
+//!```ignore,toml
+#![doc = include_str!("../examples/simple.rs")]
+//!```
+//!
+//! [^nightly]: If you are on an ARM platform, you need to install a recent nightly toolchain. After
+//!             installing, we advise to issue `rustup override set nightly` in the top-level directory.
 pub use circuit::builder::{
     CircuitBuilder, SharedCircuit, SubCircuitGate, SubCircuitInput, SubCircuitOutput,
 };
 pub use circuit::dyn_layers::Circuit;
 pub use circuit::GateId;
 pub use parse::bristol;
 pub use protocols::boolean_gmw::BooleanGate;
+pub use seec_channel as channel;
 pub use seec_macros::sub_circuit;
 
 #[cfg(feature = "bench-api")]