Working.

Author: wolfmcnally

Cargo.toml

@@ -7,12 +7,13 @@ authors = ["Blockchain Commons"]
 keywords = ["cryptography"]
 repository = "https://github.com/BlockchainCommons/bc-sskr-rust"
 readme = "README.md"
+license = "BSD-2-Clause-Patent"
 categories = ["cryptography"]
 documentation = "https://docs.rs/sskr"
 
 [dependencies]
-bc-crypto = { path = "../bc-crypto-rust" }
-bc-shamir = { path = "../bc-shamir-rust" }
+bc-crypto = "0.1.0"
+bc-shamir = "0.1.0"
 
 [dev-dependencies]
 hex-literal = "0.4.1"

LICENSE.md

@@ -1,21 +1,47 @@
-Unless otherwise noted (either in /README.md or in the file's header comments) the contents of this repository are released under the following license:
+Copyright © 2023 Blockchain Commons, LLC
 
-BSD-2-Clause Plus Patent License
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
 
-SPDX-License-Identifier: [BSD-2-Clause-Patent](https://spdx.org/licenses/BSD-2-Clause-Patent.html)
+    1. Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
 
-Copyright © 2019 Blockchain Commons, LLC
+    2. Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
 
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+Subject to the terms and conditions of this license, each copyright holder and
+contributor hereby grants to those receiving rights under this license a
+perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except for failure to satisfy the conditions of this license) patent license to
+make, have made, use, offer to sell, sell, import, and otherwise transfer this
+software, where such license applies only to those patent claims, already
+acquired or hereafter acquired, licensable by such copyright holder or
+contributor that are necessarily infringed by:
 
-1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-Subject to the terms and conditions of this license, each copyright holder and contributor hereby grants to those receiving rights under this license a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except for failure to satisfy the conditions of this license) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer this software, where such license applies only to those patent claims, already acquired or hereafter acquired, licensable by such copyright holder or contributor that are necessarily infringed by:
+    (a) their Contribution(s) (the licensed copyrights of copyright holders and
+    non-copyrightable additions of contributors, in source or binary form)
+    alone; or
 
-(a) their Contribution(s) (the licensed copyrights of copyright holders and non-copyrightable additions of contributors, in source or binary form) alone; or
-(b) combination of their Contribution(s) with the work of authorship to which such Contribution(s) was added by such copyright holder or contributor, if, at the time the Contribution is added, such addition causes such combination to be necessarily infringed. The patent license shall not apply to any other combinations which include the Contribution.
-Except as expressly stated above, no rights or licenses from any copyright holder or contributor is granted under this license, whether expressly, by implication, estoppel or otherwise.
+    (b) combination of their Contribution(s) with the work of authorship to
+    which such Contribution(s) was added by such copyright holder or
+    contributor, if, at the time the Contribution is added, such addition causes
+    such combination to be necessarily infringed. The patent license shall not
+    apply to any other combinations which include the Contribution.
+
+Except as expressly stated above, no rights or licenses from any copyright
+holder or contributor is granted under this license, whether expressly, by
+implication, estoppel or otherwise.
 
 DISCLAIMER
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -8,6 +8,8 @@
 
 ## Introduction
 
+Sharded Secret Key Reconstruction (SSKR) is a protocol for splitting a *secret* into a set of *shares* across one or more *groups*, such that the secret can be reconstructed from any combination of shares totaling or exceeding a *threshold* number of shares within each group and across all groups. SSKR is a generalization of Shamir's Secret Sharing (SSS) that allows for multiple groups and multiple thresholds.
+
 ## Getting Started
 
 ```toml
@@ -17,9 +19,11 @@ sskr = "0.1.0"
 
 ## Specification
 
+SSKR is described in [BCR-2020-011](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-011-sskr.md).
 
 ## Related Projects
 
+- [bc-shamir](https://crates.io/crates/bc-shamir) - Shamir's Secret Sharing for Rust
 
 ## Status - Alpha
 

src/encoding.rs

@@ -1,6 +1,67 @@
 use bc_crypto::RandomNumberGenerator;
 use bc_shamir::{split_secret, recover_secret};
-use crate::{Error, SSKRShare, METADATA_SIZE_BYTES, Secret, Spec};
+use crate::{Error, METADATA_SIZE_BYTES, Secret, Spec, share::SSKRShare};
+
+/// Generates SSKR shares for the given `Spec` and `Secret`.
+///
+/// # Arguments
+///
+/// * `spec` - The `Spec` instance that defines the group and member thresholds.
+/// * `master_secret` - The `Secret` instance to be split into shares.
+pub fn sskr_generate(
+    spec: &Spec,
+    master_secret: &Secret
+) -> Result<Vec<Vec<Vec<u8>>>, Error> {
+    let mut rng = bc_crypto::SecureRandomNumberGenerator;
+    sskr_generate_using(spec, master_secret, &mut rng)
+}
+
+/// Generates SSKR shares for the given `Spec` and `Secret` using the provided
+/// random number generator.
+///
+/// # Arguments
+///
+/// * `spec` - The `Spec` instance that defines the group and member thresholds.
+/// * `master_secret` - The `Secret` instance to be split into shares.
+/// * `random_generator` - The random number generator to use for generating
+///   shares.
+pub fn sskr_generate_using(
+    spec: &Spec,
+    master_secret: &Secret,
+    random_generator: &mut impl RandomNumberGenerator
+) -> Result<Vec<Vec<Vec<u8>>>, Error> {
+    let groups_shares = generate_shares(spec, master_secret, random_generator)?;
+
+    let result: Vec<Vec<Vec<u8>>> = groups_shares.iter().map (|group| {
+        group.iter().map(serialize_share).collect()
+    }).collect();
+
+    Ok(result)
+}
+
+/// Combines the given SSKR shares into a `Secret`.
+///
+/// # Arguments
+///
+/// * `shares` - A slice of SSKR shares to be combined.
+///
+/// # Errors
+///
+/// Returns an error if the shares do not meet the necessary quorum of groups
+/// and member shares within each group.
+pub fn sskr_combine<T>(shares: &[T]) -> Result<Secret, Error>
+where
+    T: AsRef<[u8]>
+{
+    let mut sskr_shares = Vec::with_capacity(shares.len());
+
+    for share in shares {
+        let sskr_share = deserialize_share(share.as_ref())?;
+        sskr_shares.push(sskr_share);
+    }
+
+    combine_shares(&sskr_shares)
+}
 
 fn serialize_share(share: &SSKRShare) -> Vec<u8> {
     // pack the id, group and member data into 5 bytes:
@@ -38,25 +99,25 @@ fn serialize_share(share: &SSKRShare) -> Vec<u8> {
 
 fn deserialize_share(source: &[u8]) -> Result<SSKRShare, Error> {
     if source.len() < METADATA_SIZE_BYTES {
-        return Err(Error::NotEnoughSerializedBytes);
+        return Err(Error::ShareLengthInvalid);
     }
 
     let group_threshold = ((source[2] >> 4) + 1) as usize;
     let group_count = ((source[2] & 0xf) + 1) as usize;
 
     if group_threshold > group_count {
-        return Err(Error::InvalidGroupThreshold);
+        return Err(Error::GroupThresholdInvalid);
     }
 
     let identifier = ((source[0] as u16) << 8) | source[1] as u16;
     let group_index = (source[3] >> 4) as usize;
     let member_threshold = ((source[3] & 0xf) + 1) as usize;
     let reserved = source[4] >> 4;
     if reserved != 0 {
-        return Err(Error::InvalidReservedBits);
+        return Err(Error::ShareReservedBitsInvalid);
     }
     let member_index = (source[4] & 0xf) as usize;
-    let value = Secret::new(source[METADATA_SIZE_BYTES..].to_vec())?;
+    let value = Secret::new(&source[METADATA_SIZE_BYTES..])?;
 
     Ok(SSKRShare::new(
         identifier,
@@ -106,28 +167,6 @@ fn generate_shares(
     Ok(groups_shares)
 }
 
-pub fn sskr_generate_using(
-    spec: &Spec,
-    master_secret: &Secret,
-    random_generator: &mut impl RandomNumberGenerator
-) -> Result<Vec<Vec<Vec<u8>>>, Error> {
-    let groups_shares = generate_shares(spec, master_secret, random_generator)?;
-
-    let result: Vec<Vec<Vec<u8>>> = groups_shares.iter().map (|group| {
-        group.iter().map(serialize_share).collect()
-    }).collect();
-
-    Ok(result)
-}
-
-pub fn sskr_generate(
-    spec: &Spec,
-    master_secret: &Secret
-) -> Result<Vec<Vec<Vec<u8>>>, Error> {
-    let mut rng = bc_crypto::SecureRandomNumberGenerator;
-    sskr_generate_using(spec, master_secret, &mut rng)
-}
-
 #[derive(Debug)]
 struct Group {
     group_index: usize,
@@ -155,7 +194,7 @@ fn combine_shares(shares: &[SSKRShare]) -> Result<Secret, Error> {
     let mut group_count = 0;
 
     if shares.is_empty() {
-        return Err(Error::EmptyShareSet);
+        return Err(Error::SharesEmpty);
     }
 
     let mut next_group = 0;
@@ -176,7 +215,7 @@ fn combine_shares(shares: &[SSKRShare]) -> Result<Secret, Error> {
                 share.group_count() != group_count ||
                 share.value().len() != secret_len
             {
-                return Err(Error::InvalidShareSet);
+                return Err(Error::ShareSetInvalid);
             }
         }
 
@@ -186,7 +225,7 @@ fn combine_shares(shares: &[SSKRShare]) -> Result<Secret, Error> {
             if share.group_index() == group.group_index {
                 group_found = true;
                 if share.member_threshold() != group.member_threshold {
-                    return Err(Error::InvalidMemberThreshold);
+                    return Err(Error::MemberThresholdInvalid);
                 }
                 for k in 0..group.count {
                     if share.member_index() == group.member_indexes[k] {
@@ -228,17 +267,3 @@ fn combine_shares(shares: &[SSKRShare]) -> Result<Secret, Error> {
 
     Ok(master_secret)
 }
-
-pub fn sskr_combine<T>(shares: &[T]) -> Result<Secret, Error>
-where
-    T: AsRef<[u8]>
-{
-    let mut sskr_shares = Vec::with_capacity(shares.len());
-
-    for share in shares {
-        let sskr_share = deserialize_share(share.as_ref())?;
-        sskr_shares.push(sskr_share);
-    }
-
-    combine_shares(&sskr_shares)
-}

src/error.rs

@@ -1,39 +1,65 @@
+/// Errors that can occur when using the SSKR library.
 #[derive(Debug, PartialEq)]
 pub enum Error {
-    NotEnoughShares,
-    TooManyShares,
-    SecretTooShort,
-    SecretTooLong,
-    SecretLengthNotEven,
-    NotEnoughSerializedBytes,
-    InvalidGroupThreshold,
-    InvalidReservedBits,
-    InvalidMemberThreshold,
-    InvalidSingletonMember,
-    EmptyShareSet,
-    InvalidShareSet,
+    /// When combining shares, the provided shares contained a duplicate member index.
     DuplicateMemberIndex,
+
+    /// When creating a split spec, the group count is invalid.
+    GroupCountInvalid,
+
+    /// When creating a split spec, the group threshold is invalid.
+    GroupThresholdInvalid,
+
+    /// When creating a group spec, the member count is invalid.
+    MemberCountInvalid,
+
+    /// When creating a group spec, the member threshold is invalid.
+    MemberThresholdInvalid,
+
+    /// When combining shares, the provided shares did not contain enough groups.
     NotEnoughGroups,
+
+    /// When creating a secret, the secret is not of even length.
+    SecretLengthNotEven,
+
+    /// When creating a secret, the secret is too long.
+    SecretTooLong,
+
+    /// When creating a secret, the secret is too short.
+    SecretTooShort,
+
+    /// When combining shares, the provided shares did not contain enough serialized bytes.
+    ShareLengthInvalid,
+
+    /// When combining shares, the provided shares contained invalid reserved bits.
+    ShareReservedBitsInvalid,
+
+    /// When combining shares, the provided shares were empty.
+    SharesEmpty,
+
+    /// When combining shares, the provided shares were invalid.
+    ShareSetInvalid,
+
+    /// An error returned from the `bc-shamir` crate.
     ShamirError(bc_shamir::Error),
 }
 
 impl std::fmt::Display for Error {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match *self {
-            Error::NotEnoughShares => write!(f, "Not enough shares"),
-            Error::TooManyShares => write!(f, "Too many shares"),
-            Error::SecretTooLong => write!(f, "Secret is too long"),
-            Error::SecretTooShort => write!(f, "Secret is too short"),
-            Error::SecretLengthNotEven => write!(f, "Secret is not of even length"),
-            Error::NotEnoughSerializedBytes => write!(f, "Not enough serialized bytes"),
-            Error::InvalidGroupThreshold => write!(f, "Invalid group threshold"),
-            Error::InvalidReservedBits => write!(f, "Invalid reserved bits"),
-            Error::InvalidMemberThreshold => write!(f, "Invalid member threshold"),
-            Error::InvalidSingletonMember => write!(f, "Invalid singleton member"),
-            Error::EmptyShareSet => write!(f, "Empty share set"),
-            Error::InvalidShareSet => write!(f, "Invalid share set"),
             Error::DuplicateMemberIndex => write!(f, "Duplicate member index"),
+            Error::GroupCountInvalid => write!(f, "Invalid group count"),
+            Error::GroupThresholdInvalid => write!(f, "Invalid group threshold"),
+            Error::MemberCountInvalid => write!(f, "Not enough shares"),
+            Error::MemberThresholdInvalid => write!(f, "Invalid member threshold"),
             Error::NotEnoughGroups => write!(f, "Not enough groups"),
+            Error::SecretLengthNotEven => write!(f, "Secret is not of even length"),
+            Error::SecretTooLong => write!(f, "Secret is too long"),
+            Error::SecretTooShort => write!(f, "Secret is too short"),
+            Error::ShareLengthInvalid => write!(f, "Not enough serialized bytes"),
+            Error::ShareReservedBitsInvalid => write!(f, "Invalid reserved bits"),
+            Error::SharesEmpty => write!(f, "Empty share set"),
+            Error::ShareSetInvalid => write!(f, "Invalid share set"),
             Error::ShamirError(ref e) => write!(f, "{}", e),
         }
     }