From badd0ba4b7109db305626aea443261f6071f6c1d Mon Sep 17 00:00:00 2001 From: Ralph Giles Date: Thu, 14 Sep 2023 08:41:23 -0700 Subject: [PATCH 1/4] adss: Add a changelog Record release notes so there's something to publish with updates. Result of `cargo changelog --write` followed by manual edits, especially for the unreleased versions. --- adss/CHANGELOG.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 adss/CHANGELOG.md diff --git a/adss/CHANGELOG.md b/adss/CHANGELOG.md new file mode 100644 index 00000000..f92efcdf --- /dev/null +++ b/adss/CHANGELOG.md @@ -0,0 +1,40 @@ +# Changelog + +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). + +## v0.2.2 (2023-09-14) + + - Avoid `Share::from_bytes` panic when serialized share is too small + +## v0.2.1 (2023-07-19) + + - Update crate metadata + Fill out Cargo.toml to meet crates.io publication requirements. + - Vendor strobe-rng to allow publication. + +### Commit Details + + + +
view details + + * **Uncategorized** + - Merge pull request #275 from brave/adss-0.2.1 (f2300de) + - Bump version number for adss-0.2.1 (0124edc) + - Update crate metadata (8ad7543) + - Rename adss-rs to plain adss (29fbd42) +
+ +## v0.2.0 (unreleased, 2023 March 31) + +- Clear key material after use (zeroize) +- Documentation fixes +- API cleanup +- Update deps + +## v0.1.3 (unreleased, circa 2021 September) + +- Initial version used with Web Discovery Project From e43fc8e424adec9d2451dfefa8934c86b0e1318b Mon Sep 17 00:00:00 2001 From: Ralph Giles Date: Thu, 14 Sep 2023 08:49:37 -0700 Subject: [PATCH 2/4] adss: Link to changelog from the readme --- adss/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/adss/README.md b/adss/README.md index 876f73a6..fd0972f0 100644 --- a/adss/README.md +++ b/adss/README.md @@ -8,6 +8,9 @@ WARNING the libraries present in this workspace have not been audited, use at your own risk! This code is under active development and may change substantially in future versions. +See the [changelog](CHANGELOG.md) for information about different +versions. + ## Quickstart Build & test: From dddd61452e53029db86831dc743dbb89b4aa1e20 Mon Sep 17 00:00:00 2001 From: Ralph Giles Date: Thu, 14 Sep 2023 08:50:51 -0700 Subject: [PATCH 3/4] adss: Remove obsolete benchmark instructions There aren't any local benchmarks for this crate. --- adss/README.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/adss/README.md b/adss/README.md index fd0972f0..12dc9f11 100644 --- a/adss/README.md +++ b/adss/README.md @@ -19,12 +19,7 @@ cargo build cargo test ``` -Benchmarks: -``` -cargo bench -``` - -Open local copy of documentation: +Open a local copy of the documentation: ``` cargo doc --open --no-deps ``` From d0ef0db8863c9121f53b03b8d57ab0e24165bfe2 Mon Sep 17 00:00:00 2001 From: Ralph Giles Date: Thu, 14 Sep 2023 09:34:48 -0700 Subject: [PATCH 4/4] adss: Document more methods Fill out the documentation a bit, so top-level elements at least have a one-line description. --- adss/src/lib.rs | 39 ++++++++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/adss/src/lib.rs b/adss/src/lib.rs index 21ee0e29..8ae7448f 100644 --- a/adss/src/lib.rs +++ b/adss/src/lib.rs @@ -2,8 +2,8 @@ //! sharing with established security guarantees. We use this framework //! as it allows for specifying the random coins that are used for //! establishing the lagrange polynomial coefficients explicitly. A -//! description of the framework is provided in the paper by [Bellare et -//! al.](https://eprint.iacr.org/2020/800). +//! description of the Adept Secret Sharing framework is provided in +//! the paper by [Bellare et al.](https://eprint.iacr.org/2020/800). use star_sharks::Sharks; use std::convert::{TryFrom, TryInto}; @@ -15,10 +15,10 @@ use zeroize::{Zeroize, ZeroizeOnDrop}; mod strobe_rng; use strobe_rng::StrobeRng; -// The length of a `AccessStructure`, in bytes. +/// The length of a serialized `AccessStructure`, in bytes. pub const ACCESS_STRUCTURE_LENGTH: usize = 4; -// The length of a `Share::J`, in bytes. +/// The length of a message authentication code used in `Share`, in bytes. pub const MAC_LENGTH: usize = 64; /// The `AccessStructure` struct defines the policy under which shares @@ -29,10 +29,12 @@ pub struct AccessStructure { threshold: u32, } +/// Append a `u32` in little-endian coding pub fn store_u32(u: u32, out: &mut Vec) { out.extend(u.to_le_bytes()); } +/// Attempt to parse a little-endian value from a byte serialization pub fn load_u32(bytes: &[u8]) -> Option { if bytes.len() != 4 { return None; @@ -43,11 +45,24 @@ pub fn load_u32(bytes: &[u8]) -> Option { Some(u32::from_le_bytes(bits)) } +/// Append a chunk of data +/// +/// Extends the output `Vec` with the passed slice, prepending +/// a 4-byte, little-endian length header so it can be parsed +/// out later. pub fn store_bytes(s: &[u8], out: &mut Vec) { store_u32(s.len() as u32, out); out.extend(s); } +/// Parse the next data chunk out of a byte slice +/// +/// This reads a 4-byte, little-endian length header and +/// then returns a new slice with the data bounded by +/// that header. +/// +/// Returns `None` if there is insufficient data for +/// the complete chunk. pub fn load_bytes(bytes: &[u8]) -> Option<&[u8]> { if bytes.len() < 4 { return None; @@ -64,13 +79,17 @@ pub fn load_bytes(bytes: &[u8]) -> Option<&[u8]> { /// An `AccessStructure` defines how a message is to be split among multiple parties /// /// In particular this determines how many shares will be issued and what threshold of the shares -/// are needed to reconstruct the original `Commune` +/// are needed to reconstruct the original `Commune`. impl AccessStructure { /// Convert this `AccessStructure` to a byte array. pub fn to_bytes(&self) -> [u8; ACCESS_STRUCTURE_LENGTH] { self.threshold.to_le_bytes() } + /// Parse a serialized `AccessStructure` from a byte slice. + /// + /// Returns `None` if a valid structure was not found, for + /// example if the slice was too short. pub fn from_bytes(bytes: &[u8]) -> Option { let threshold = load_u32(bytes)?; Some(AccessStructure { threshold }) @@ -84,11 +103,13 @@ impl From for Sharks { } } -/// A `Commune` is a unique instance of sharing across multiple parties +/// A a unique instance of sharing across multiple parties /// -/// It consists of an access structure defining the parameters of the sharing, a secret message -/// which will be shared, "random coins" which provide strong but possibly non-uniform entropy -/// and an optional STROBE transcript which can include extra data which will be authenticated. +/// A `Commune` consists of an access structure defining the +/// parameters of the sharing, a secret message which will be shared, +/// "random coins" which provide strong but possibly non-uniform +/// entropy and an optional STROBE transcript which can include +/// extra data which will be authenticated. #[cfg_attr(not(feature = "cbindgen"), repr(C))] #[allow(non_snake_case)] #[derive(Clone, ZeroizeOnDrop)]