fixed typos, cleaned up docs, added unit and bench tests

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2020-01-22
+### Added
+- Share struct which allows to convert from/to byte vectors
+
+### Changed
+- Methods use the new Share struct, instead of (GF245, Vec<GF256>) tuples
+
 ## [0.2.0] - 2020-01-21
 ### Added
 - Computations performed over GF256 (much faster)

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sharks"
-version = "0.2.0"
+version = "0.3.0"
 authors = ["Aitor Ruano <codearm@pm.me>"]
 description = "Fast, small and secure Shamir's Secret Sharing library crate"
 homepage = "https://github.com/c0dearm/sharks"

README.md

@@ -45,9 +45,9 @@ You can run them with `cargo test` and `cargo bench`.
 
 ### Benchmark results [min mean max]
 
-| CPU                                       | obtain_shares_dealer            | step_shares_dealer              | recover_secret                  |
-| ----------------------------------------- | ------------------------------- | ------------------------------- | ------------------------------- |
-| Intel(R) Core(TM) i7-8550U CPU @ 1.80GHz  | [1.4321 us 1.4339 us 1.4357 us] | [1.3385 ns 1.3456 ns 1.3552 ns] | [228.77 us 232.17 us 236.23 us] |
+| CPU                                       | obtain_shares_dealer            | step_shares_dealer              | recover_secret                  | share_from_bytes                | share_to_bytes                  |
+| ----------------------------------------- | ------------------------------- | ------------------------------- | ------------------------------- | ------------------------------- | ------------------------------- |
+| Intel(R) Core(TM) i7-8550U CPU @ 1.80GHz  | [1.4321 us 1.4339 us 1.4357 us] | [1.3385 ns 1.3456 ns 1.3552 ns] | [228.77 us 232.17 us 236.23 us] | [24.688 ns 25.083 ns 25.551 ns] | [22.832 ns 22.910 ns 22.995 ns] |
 
 # Contributing
 

benches/benchmarks.rs

@@ -1,6 +1,6 @@
 use criterion::{black_box, criterion_group, criterion_main, Criterion};
 
-use sharks::Sharks;
+use sharks::{Share, Sharks};
 
 fn dealer(c: &mut Criterion) {
     let sharks = Sharks(255);
@@ -14,12 +14,26 @@ fn dealer(c: &mut Criterion) {
 
 fn recover(c: &mut Criterion) {
     let sharks = Sharks(255);
-    let shares = sharks.dealer(&[1]).take(255).collect();
+    let shares: Vec<Share> = sharks.dealer(&[1]).take(255).collect();
 
     c.bench_function("recover_secret", |b| {
-        b.iter(|| sharks.recover(black_box(&shares)))
+        b.iter(|| sharks.recover(black_box(shares.as_slice())))
     });
 }
 
-criterion_group!(benches, dealer, recover);
+fn share(c: &mut Criterion) {
+    let bytes_vec = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    let bytes = bytes_vec.as_slice();
+    let share = Share::from(bytes);
+
+    c.bench_function("share_from_bytes", |b| {
+        b.iter(|| Share::from(black_box(bytes)))
+    });
+
+    c.bench_function("share_to_bytes", |b| {
+        b.iter(|| Vec::from(black_box(&share)))
+    });
+}
+
+criterion_group!(benches, dealer, recover, share);
 criterion_main!(benches);

src/lib.rs

@@ -11,7 +11,7 @@
 //! // Get 10 shares
 //! let shares: Vec<Share> = dealer.take(10).collect();
 //! // Recover the original secret!
-//! let secret = sharks.recover(&shares).unwrap();
+//! let secret = sharks.recover(shares.as_slice()).unwrap();
 //! assert_eq!(secret, vec![1, 2, 3, 4]);
 //! ```
 
@@ -35,7 +35,7 @@ pub use share::Share;
 /// // Get 10 shares
 /// let shares: Vec<Share> = dealer.take(10).collect();
 /// // Recover the original secret!
-/// let secret = sharks.recover(&shares).unwrap();
+/// let secret = sharks.recover(shares.as_slice()).unwrap();
 /// assert_eq!(secret, vec![1, 2, 3, 4]);
 /// ```
 pub struct Sharks(pub u8);
@@ -81,6 +81,8 @@ impl Sharks {
     /// // Not enough shares to recover secret
     /// assert!(secret.is_err());
     pub fn recover(&self, shares: &[Share]) -> Result<Vec<u8>, &str> {
+        // TODO: Discuss use of slice instead of hashmap here
+
         if shares.len() < self.0 as usize {
             Err("Not enough shares to recover original secret")
         } else {

src/math.rs

@@ -10,9 +10,7 @@ use super::share::Share;
 // Where each (key, value) pair corresponds to one share, where the key is the `x` and the value is a vector of `y`,
 // where each element corresponds to one of the secret's byte chunks.
 pub fn interpolate(shares: &[Share]) -> Vec<u8> {
-    let n_chunks = shares[0].y.len();
-
-    (0..n_chunks)
+    (0..shares[0].y.len())
         .map(|s| {
             shares
                 .iter()

src/share.rs

@@ -1,53 +1,42 @@
-use crate::GF256;
+use super::field::GF256;
 
-/// A share used for to reconstruct the secret. Can be serialized to and from a byte array for transmission.
+/// A share used to reconstruct the secret. Can be serialized to and from a byte array.
 ///
-/// Example:
+/// Usage example:
 /// ```
-/// # use std::borrow::Borrow;
-/// # fn send_to_printer(_: Vec<u8>) { }
-/// # fn ask_shares() -> Vec<Vec<u8>> { vec![] }
+/// use sharks::{Sharks, Share};
+/// # fn send_to_printer(_: Vec<u8>) {}
+/// # fn ask_shares() -> Vec<Vec<u8>> {vec![vec![1, 2], vec![2, 3], vec![3, 4]]}
 ///
-/// # use sharks::{ Sharks, Share };
+/// // Transmit the share bytes to a printer
 /// let sharks = Sharks(3);
-/// // Obtain an iterator over the shares for secret [1, 2]
 /// let dealer = sharks.dealer(&[1, 2, 3]);
 ///
-/// # let mut shares: Vec<Vec<u8>> = Vec::with_capacity(5);
 /// // Get 5 shares and print paper keys
 /// for s in dealer.take(5) {
-///     println!("test");
-///     # shares.push(s.clone().into());
-///     send_to_printer(s.into());
+///     send_to_printer(Vec::from(&s));
 /// };
 ///
-/// # let shares = vec![shares[0].clone(), shares[2].clone(), shares[4].clone()];
-///
-/// // Get 3 shares from users and get secret
-/// let shares_serialized: Vec<Vec<u8>> = ask_shares();
-/// # let shares_serialized = shares;
-///
-/// let shares: Vec<Share> = shares_serialized.iter().map(|s| s.as_slice().into()).collect();
-///
-/// let secret = sharks.recover(&shares).expect("we should have at leats 3 shares");
-///
-/// assert_eq!(secret, vec![1, 2, 3]);
-#[derive(Debug, Clone)]
+/// // Get share bytes from an external source and recover secret
+/// let shares_bytes: Vec<Vec<u8>> = ask_shares();
+/// let shares: Vec<Share> = shares_bytes.iter().map(|s| Share::from(s.as_slice())).collect();
+/// let secret = sharks.recover(&shares).unwrap();
 pub struct Share {
     pub x: GF256,
     pub y: Vec<GF256>,
 }
 
-impl From<Share> for Vec<u8> {
-    fn from(s: Share) -> Vec<u8> {
-        let mut serialized: Vec<u8> = Vec::with_capacity(s.y.len() + 1);
-        serialized.push(s.x.0);
-
-        serialized.append(&mut s.y.iter().map(|p| p.0).collect());
-        serialized
+/// Obtains a byte vector from a `Share` instance
+impl From<&Share> for Vec<u8> {
+    fn from(s: &Share) -> Vec<u8> {
+        let mut bytes = Vec::with_capacity(s.y.len() + 1);
+        bytes.push(s.x.0);
+        bytes.extend(s.y.iter().map(|p| p.0));
+        bytes
     }
 }
 
+/// Obtains a `Share` instance from a byte slice
 impl From<&[u8]> for Share {
     fn from(s: &[u8]) -> Share {
         let x = GF256(s[0]);
@@ -55,3 +44,26 @@ impl From<&[u8]> for Share {
         Share { x, y }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{Share, GF256};
+
+    #[test]
+    fn vec_from_share_works() {
+        let share = Share {
+            x: GF256(1),
+            y: vec![GF256(2), GF256(3)],
+        };
+        let bytes = Vec::from(&share);
+        assert_eq!(bytes, vec![1, 2, 3]);
+    }
+
+    #[test]
+    fn share_from_u8_slice_works() {
+        let bytes = [1, 2, 3];
+        let share = Share::from(&bytes[..]);
+        assert_eq!(share.x, GF256(1));
+        assert_eq!(share.y, vec![GF256(2), GF256(3)]);
+    }
+}