tss 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dd575aedfcbdae566a0c2005c129da4e670b0c50
-  data.tar.gz: 85801386f03fcd06b29acea57c166149ddf22bb8
+  metadata.gz: 53a46eaf5b6ac5b816d288d0ed9379dc59679145
+  data.tar.gz: 19fa36c7c3ef3d6e42c5a69cbe8a227a4985dfb8
 SHA512:
-  metadata.gz: 6727e7bd3a7d758cccc93b780adb028164ca51cf47f56fb41f4e20468cbefb7d73de054f90c199e82ff49ac3091c438ea900efd05977d39bb4cb83cab510ff86
-  data.tar.gz: 9f6dbd3a9061eb6fe986042e39591dc7a0a2ecf9bdb139ab48220631cd1d966603ccdf3c75d3d2f09528580bdfab665e072e3431ec5c479b0820b5f3685115b2
+  metadata.gz: 88160d1aedccbac904ee0850fe987e85c67de3754ba6182d646932d3c8ec3de22098bfc99309371706a5b7e291c878dfff6cb00afec6c584f162abb8cf4d6689
+  data.tar.gz: 66987ba2804b48a4a8d5ba79065e719c78aaf8c0deaec74974b5fa4a5a48127ff72a5d6d2b7cf84920995dac7c7d842b808b0763ce179bf60714b75989ea2668

data/.yardopts

@@ -0,0 +1 @@
+--no-private  lib/**/*.rb - README.md LICENSE.txt CODE_OF_CONDUCT.md

data/README.md

@@ -1,14 +1,15 @@
 # TSS - Threshold Secret Sharing
 
+[![Gem Version](https://badge.fury.io/rb/tss.svg)](https://badge.fury.io/rb/tss)
 [![Build Status](https://travis-ci.org/grempe/tss-rb.svg?branch=master)](https://travis-ci.org/grempe/tss-rb)
 [![Coverage Status](https://coveralls.io/repos/github/grempe/tss-rb/badge.svg?branch=master)](https://coveralls.io/github/grempe/tss-rb?branch=master)
 [![Code Climate](https://codeclimate.com/github/grempe/tss-rb/badges/gpa.svg)](https://codeclimate.com/github/grempe/tss-rb)
 
-## WARNING : PRE-ALPHA CODE
+## WARNING : BETA CODE
 
-This code is currently a work in progress and is not yet ready for production
-use. The API, input and output formats, and other aspects are likely to change
-before release. There has been no security review of this code.
+This code is new and has not yet been tested in production. Use at your own risk.
+The share format and interface should be fairly stable now but should not be
+considered fully stable until v1.0.0 is released.
 
 ## About TSS
 
@@ -43,6 +44,112 @@ hash for the secret is not available to shareholders prior to recombining shares
 The specification also addresses the optional implementation of a `MAGIC_NUMBER` and
 advanced error correction schemes. These extras are not currently implemented.
 
+## TL;DR
+
+No time for docs? Here is how to get going in 10 seconds or less with the
+CLI or in Ruby. The CLI defaults to using `human` shares, and Ruby defaults
+to a binary octet string representation. The default is `3 out of 5` threshold
+sharing.
+
+### CLI (Human Shares)
+
+```text
+~/src$ gem install tss
+Successfully installed tss-0.1.0
+1 gem installed
+~/src$ tss split
+Enter your secret:
+secret >  my deep dark secret
+tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQBDoW7GJ66g6nQHQZVM_iUxMVEO7NHlwDaEM5FYsVwhBSfio-WF-w2gqSKRjBp6YyqTQKR
+tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQCxKBLxPsXuW4e7xE0zKiso49aEyuMKNIhjISe7ga865KDnBBpE1iZ6ESUkaWojKE3yNbc
+tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQDp1zQuADISueqk2UK3yNdBDh7XGlyoD2R6X9y-BCoI7iwAE02A8aj8vKO9ticeJpQMvDi
+tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQEgzj1RJXwKbu0pa5Z5qssmoX0cz22gVg8UCc6tasiqbDNi7bq_xKUczpYuc7utwDyPxV1
+tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQF4MRuOG4v2jIA2dpn9SDdPTLVPH9ICbeMNdzWo702YZr-F-u174yuaYxC3rPaQzuVxTNL
+~/src$ tss combine
+Enter shares, one per line, blank line or dot (.) to finish:
+share>  tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQBDoW7GJ66g6nQHQZVM_iUxMVEO7NHlwDaEM5FYsVwhBSfio-WF-w2gqSKRjBp6YyqTQKR
+share>  tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQCxKBLxPsXuW4e7xE0zKiso49aEyuMKNIhjISe7ga865KDnBBpE1iZ6ESUkaWojKE3yNbc
+share>  tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQDp1zQuADISueqk2UK3yNdBDh7XGlyoD2R6X9y-BCoI7iwAE02A8aj8vKO9ticeJpQMvDi
+share>  .
+
+Secret Recovered and Verified!
+
+identifier : 4a993275528d5ec7
+threshold : 3
+processing time (ms) : 0.64
+secret :
+**************************************************
+my deep dark secret
+**************************************************
+```
+
+### Ruby (Binary Octet Shares)
+
+```text
+~/src$ irb
+irb(main):001:0> require 'tss'
+=> true
+irb(main):002:0> shares = TSS.split(secret: 'my deep dark secret')
+=> ["ab87eb60ae14dd87\x02\x03\x004\x01\xC6+\xC8\x9F\xE4\x7F\x85\x17\xBD\xF6\xE6\xE3m\xB9\xFF\x8CGoS\x90\xB0{\xAB\x04N\xE2\x8F\xA0\xDC\x06\xC7Y\xBE\xCD?\xBDe9\xF3\xDF\xEA\xC9s\x105\xA4\xD8TZw\x9E", "ab87eb60ae14dd87\x02\x03\x004\x02T\xBB\xEF\x12\x81\xE2\xD2\x8Et\x95\x8Eg\xE6x=HD8\xAD\xE5\xF2'OdBO4vL\xF90\xA5c\x82\xE8\x11\x94\x8E\xEEV\xB3\xAFh\xB7\x80Ac\x15\xD9\xC7\x93", "ab87eb60ae14dd87\x02\x03\x004\x03\xFF\xE9\a\xE9\x00\xF8'\xB9\xAD\x02\x1A\xEF\xAB\xB2\xA7\xA7q2\x8A\x84\xFBC\v\ny\x98\x12\xA2C\x9B\xBB\xC2qY\x05e\xF6\xC5\x11\x11K\xF6:\xEA\xE8\xF8\f\x8C4\x94\xA2", "ab87eb60ae14dd87\x02\x03\x004\x04\xD4e\xB5\xD2o\x8AxJ\x96\xBB\x80o\xDCC\x12\xA0u\xE0\xB7\xACP\x82\x14\x13\x04\xD0\xE1\x82\xC4:k\\\xA8\xC1g\xA2}\"\xCF\x04x\xEC*\xB9\xC8q,\x8F\xE1\xF6\xB4", "ab87eb60ae14dd87\x02\x03\x004\x05\x7F7])\xEE\x90\x8D}O,\x14\xE7\x91\x89\x88O@\xEA\x90\xCDY\xE6P}?\a\xC7V\xCBX\xE0;\xBA\x1A\x8A\xD6\x1Fi0C\x80\xB5x\xE4\xA0\xC8C\x16\f\xA5\x85"]
+irb(main):003:0> secret = TSS.combine(shares: shares)
+=> {:hash_alg=>"SHA256", :identifier=>"ab87eb60ae14dd87", :num_shares_provided=>5, :num_shares_used=>3, :processing_started_at=>"2016-04-13T19:37:14Z", :processing_finished_at=>"2016-04-13T19:37:14Z", :processing_time_ms=>0.63, :secret=>"my deep dark secret", :shares_select_by=>"first", :combinations=>nil, :threshold=>3}
+irb(main):004:0> puts secret[:secret]
+my deep dark secret
+=> nil
+```
+
+## Is it any good?
+
+While this implementation has not had a formal security review, the cryptographic
+underpinnings were carefully specified in an IETF draft document authored by a
+noted cryptographer. I have reached out to individuals respected in the field
+for their work in implementing cryptographic solutions to help review this code.
+
+> I've read draft-mcgrew-tss-03 and then took a look at your code.
+> Impressive! Nice docs, clean easy-to-read code. I'd use constant-time
+> comparison for hashes [[resolved : 254ecab](https://github.com/grempe/tss-rb/commit/254ecab24a338872a5b05c7446213ef1ddabf4cb)],
+> but apart from that I have nothing to add. Good job!
+>
+> -- Dmitry Chestnykh ([@dchest](https://github.com/dchest))
+>
+> [v0.1.0 : 4/13/2016]
+
+All that being said, if your threat model includes a **N**ation **S**tate **A**ctor
+the security of this particular code should probably not be your primary concern.
+
+## Suggestions for Use
+
+* Don't split large texts. Instead, split the much smaller encryption
+keys that protect encrypted large texts. Supply the encrypted
+files and the shares separately to recipients. Threshold secret sharing can be
+very slow at splitting and recombining very large bodies of text, especially
+when combined with a large number of shares. Every byte of the secret must
+be processed `num_shares` times.
+
+* Don't treat shares like encrypted data, but instead like the encryption keys
+that unlock the data. Shares are keys, and need to be protected as such. There is
+nothing to slow down an attacker if they have access to enough shares.
+
+* If you send keys by email, or some other insecure channel, then your email
+provider, or any entity with access to their data, now also has the keys to
+your data. They just need to collect enough keys to meet the threshold.
+
+* Use public key cryptography to encrypt secret shares with the public key of
+each individual recipient. This can protect the share data from unwanted use while
+in transit or at rest. Excellent choices might be
+[RbNaCl](https://github.com/cryptosphere/rbnacl)
+or [TweetNaCl.js](https://github.com/dchest/tweetnacl-js).
+
+* Put careful thought into how you want to distribute shares. It often makes
+sense to give individuals more than one share.
+
+## Supported Platforms
+
+TSS is continuously integration tested on the following Ruby VMs:
+
+* MRI 2.1, 2.2, 2.3
+
+It may work on others as well.
 
 ## Installation
 
@@ -112,30 +219,6 @@ You can also clone the repository and verify the signatures locally using your
 own GnuPG installation. You can find my certificates and read about how to conduct
 this verification at [https://www.rempe.us/keys/](https://www.rempe.us/keys/).
 
-## TSS : Suggestions for Use
-
-* Don't split large texts. Instead, split the much smaller encryption
-keys that protect encrypted large texts. Supply the encrypted
-files and the shares separately to recipients. Threshold secret sharing can be
-very slow at splitting and recombining very large bodies of text, especially
-when combined with a large number of shares. Every byte of the secret must
-be processed `num_shares` times.
-
-* Don't treat shares like encrypted data, but instead like the encryption keys
-that unlock the data. Shares are keys, and need to be protected as such. There is
-nothing to slow down an attacker if they have access to enough shares.
-
-* If you send keys by email, or some other insecure channel, then your email
-provider, or any entity with access to their data, now also has the keys to
-your data. They just need to collect enough keys to meet the threshold.
-
-* Use public key cryptography to encrypt secret shares with the public key of
-each individual recipient. This can protect the share data from unwanted use while
-in transit or at rest.
-
-* Put careful thought into how you want to distribute shares. It often makes
-sense to give individuals more than one share.
-
 ## Command Line Interface
 
 When you install the gem a simple `tss` command-line interface (CLI)
@@ -547,6 +630,9 @@ run `bundle exec rake release`, which will create a git tag for the version,
 push git commits and tags, and push the `.gem` file
 to [rubygems.org](https://rubygems.org).
 
+You can run the Command Line Interface (CLI) in development
+with `bundle exec bin/tss`.
+
 ### Contributing
 
 Bug reports and pull requests are welcome on GitHub

data/lib/tss/combiner.rb

@@ -14,92 +14,42 @@ module TSS
       .enum('first', 'sample', 'combinations')
       .default('first')
 
-    # The reconstruction, or combining, operation reconstructs the secret from a
-    # set of valid shares where the number of shares is >= the threshold when the
-    # secret was initially split. All arguments are provided in a single Hash:
+    # To reconstruct a secret from a set of shares, the following
+    # procedure, or any equivalent method, is used:
     #
-    # `shares` : The shares parameter is an Array of String shares.
+    #   If the number of shares provided as input to the secret
+    #   reconstruction operation is greater than the threshold M, then M
+    #   of those shares are selected for use in the operation.  The method
+    #   used to select the shares can be arbitrary.
     #
-    # If the number of shares provided as input to the secret
-    # reconstruction operation is greater than the threshold M, then M
-    # of those shares are selected for use in the operation.  The method
-    # used to select the shares can be chosen with the `select_by:` argument
-    # which takes the following values:
+    #   If the shares are not equal length, then the input is
+    #   inconsistent.  An error should be reported, and processing must
+    #   halt.
     #
-    # `first` : If X shares are required by the threshold and more than X
-    # shares are provided, then the first X shares in the Array of shares provided
-    # will be used. All others will be discarded and the operation will fail if
-    # those selected shares cannot recreate the secret.
+    #   The output string is initialized to the empty (zero-length) octet
+    #   string.
     #
-    # `sample` : If X shares are required by the threshold and more than X
-    # shares are provided, then X shares will be randomly selected from the Array
-    # of shares provided.  All others will be discarded and the operation will
-    # fail if those selected shares cannot recreate the secret.
+    #   The octet array U is formed by setting U[i] equal to the first
+    #   octet of the ith share.  (Note that the ordering of the shares is
+    #   arbitrary, but must be consistent throughout this algorithm.)
     #
-    # `combinations` : If X shares are required, and more than X shares are
-    # provided, then all possible combinations of the threshold number of shares
-    # will be tried to see if the secret can be recreated.
-    # This flexibility comes with a cost. All combinations of `threshold` shares
-    # must be generated. Due to the math associated with combinations it is possible
-    # that the system would try to generate a number of combinations that could never
-    # be generated or processed in many times the life of the Universe. This option
-    # can only be used if the possible combinations for the number of shares and the
-    # threshold needed to reconstruct a secret result in a number of combinations
-    # that is small enough to have a chance at being processed. If the number
-    # of combinations will be too large then the an Exception will be raised before
-    # processing has started.
+    #   The initial octet is stripped from each share.
     #
-    # If the combine operation does not result in a secret being successfully
-    # extracted, then a `TSS::Error` exception will be raised.
+    #   If any two elements of the array U have the same value, then an
+    #   error condition has occurred; this fact should be reported, then
+    #   the procedure must halt.
     #
+    #   For each octet of the shares, the following steps are performed.
+    #   An array V of M octets is created, in which the array element V[i]
+    #   contains the octet from the ith share.  The value of I(U, V) is
+    #   computed, then appended to the output string.
     #
-    # How it works:
-    #
-    #  To reconstruct a secret from a set of shares, the following
-    #  procedure, or any equivalent method, is used:
-    #
-    #     If the number of shares provided as input to the secret
-    #     reconstruction operation is greater than the threshold M, then M
-    #     of those shares are selected for use in the operation.  The method
-    #     used to select the shares can be arbitrary.
-    #
-    #     If the shares are not equal length, then the input is
-    #     inconsistent.  An error should be reported, and processing must
-    #     halt.
-    #
-    #     The output string is initialized to the empty (zero-length) octet
-    #     string.
-    #
-    #     The octet array U is formed by setting U[i] equal to the first
-    #     octet of the ith share.  (Note that the ordering of the shares is
-    #     arbitrary, but must be consistent throughout this algorithm.)
-    #
-    #     The initial octet is stripped from each share.
-    #
-    #     If any two elements of the array U have the same value, then an
-    #     error condition has occurred; this fact should be reported, then
-    #     the procedure must halt.
-    #
-    #     For each octet of the shares, the following steps are performed.
-    #     An array V of M octets is created, in which the array element V[i]
-    #     contains the octet from the ith share.  The value of I(U, V) is
-    #     computed, then appended to the output string.
-    #
-    #     The output string is returned.
+    #   The output string is returned.
     #
     def combine
-      # unwrap 'human' share format
-      if shares.first.start_with?('tss~')
-        shares.collect! do |s|
-          matcher = /^tss~v1~*[a-zA-Z0-9\.\-\_]{0,16}~[0-9]{1,3}~([a-zA-Z0-9\-\_]+\={0,2})$/
-          s_b64 = s.match(matcher)
-          if s_b64.present?
-            # puts s_b64.to_a[1].inspect
-            Base64.urlsafe_decode64(s_b64.to_a[1])
-          else
-            raise TSS::ArgumentError, 'invalid shares, human format shares do not match expected pattern'
-          end
-        end
+      # unwrap 'human' shares into binary shares
+      if all_shares_appear_human?(shares)
+        @shares = convert_shares_human_to_binary(shares)
       end
 
       validate_all_shares(shares)
@@ -120,8 +70,8 @@ module TSS
         when 'sample'
           @shares = shares.sample(threshold)
         when 'combinations'
-          share_combinations_mode_allowed?(hash_id)
-          share_combinations_out_of_bounds?(shares, threshold)
+          share_combinations_mode_allowed!(hash_id)
+          share_combinations_out_of_bounds!(shares, threshold)
         end
       end
 
@@ -132,7 +82,7 @@ module TSS
         bytestring.unpack('C*') unless bytestring.nil?
       end.compact
 
-      shares_bytes_have_valid_indexes?(shares_bytes)
+      shares_bytes_have_valid_indexes!(shares_bytes)
 
       if select_by == 'combinations'
         # Build an Array of all possible `threshold` size combinations.
@@ -141,36 +91,32 @@ module TSS
         secret = nil
         while secret.nil? && share_combos.present?
           # Check a combination and shift it off the Array
-          result = extract_secret_from_shares(hash_id, share_combos.shift)
+          result = extract_secret_from_shares!(hash_id, share_combos.shift)
           next if result.nil?
           secret = result
         end
       else
-        secret = extract_secret_from_shares(hash_id, shares_bytes)
+        secret = extract_secret_from_shares!(hash_id, shares_bytes)
       end
 
-      if secret.present?
-        {
-          hash_alg: Hasher.key_from_code(hash_id).to_s,
-          identifier: identifier,
-          num_shares_provided: orig_shares_size,
-          num_shares_used: share_combos.present? ? share_combos.first.size : shares.size,
-          processing_started_at: start_processing_time.utc.iso8601,
-          processing_finished_at: Time.now.utc.iso8601,
-          processing_time_ms: ((Time.now - start_processing_time)*1000).round(2),
-          secret: Util.bytes_to_utf8(secret),
-          shares_select_by: select_by,
-          combinations: share_combos.present? ? share_combos.size : nil,
-          threshold: threshold
-        }
-      else
-        raise TSS::Error, 'unable to recombine shares into a verifiable secret'
-      end
+      {
+        hash_alg: Hasher.key_from_code(hash_id).to_s,
+        identifier: identifier,
+        num_shares_provided: orig_shares_size,
+        num_shares_used: share_combos.present? ? share_combos.first.size : shares.size,
+        processing_started_at: start_processing_time.utc.iso8601,
+        processing_finished_at: Time.now.utc.iso8601,
+        processing_time_ms: ((Time.now - start_processing_time)*1000).round(2),
+        secret: Util.bytes_to_utf8(secret),
+        shares_select_by: select_by,
+        combinations: share_combos.present? ? share_combos.size : nil,
+        threshold: threshold
+      }
     end
 
     private
 
-    def extract_secret_from_shares(hash_id, shares_bytes)
+    def extract_secret_from_shares!(hash_id, shares_bytes)
       secret = []
 
       # build up an Array of index values from each share
@@ -198,10 +144,17 @@ module TSS
         # digest now as when it was originally created.
         new_hash_bytes = Hasher.byte_array(hash_alg, Util.bytes_to_utf8(secret))
 
-        # return the secret only if the hash test passed
-        new_hash_bytes == orig_hash_bytes ? secret : nil
+        if Util.secure_compare(Util.bytes_to_hex(orig_hash_bytes), Util.bytes_to_hex(new_hash_bytes))
+          return secret
+        else
+          raise TSS::InvalidSecretHashError, 'invalid shares, hash of secret does not equal embedded hash'
+        end
       else
-        secret
+        if secret.present?
+          return secret
+        else
+          raise TSS::NoSecretError, 'invalid shares, unable to recombine into a verifiable secret'
+        end
       end
     end
 
@@ -210,6 +163,30 @@ module TSS
       secret.shift while secret.first == 31
     end
 
+    def all_shares_appear_human?(shares)
+      shares.all? do |s|
+        # test for starting with 'tss' since regex match against
+        # binary data sometimes throws exceptions.
+        s.start_with?('tss~') && s.match(Util::HUMAN_SHARE_RE)
+      end
+    end
+
+    def convert_shares_human_to_binary(shares)
+      shares.collect do |s|
+        s_b64 = s.match(Util::HUMAN_SHARE_RE)
+        if s_b64.present? && s_b64.to_a[1].present?
+          begin
+            # the [1] capture group contains the Base64 encoded bin share
+            Base64.urlsafe_decode64(s_b64.to_a[1])
+          rescue ArgumentError
+            raise TSS::ArgumentError, 'invalid shares, some human format shares have invalid Base64 data'
+          end
+        else
+          raise TSS::ArgumentError, 'invalid shares, some human format shares do not match expected pattern'
+        end
+      end
+    end
+
     def valid_header?(header)
       header.is_a?(Hash) &&
         header.key?(:identifier) &&
@@ -222,7 +199,7 @@ module TSS
         header[:share_len].is_a?(Integer)
     end
 
-    def shares_have_same_bytesize?(shares)
+    def shares_have_same_bytesize!(shares)
       shares.each do |s|
         unless s.bytesize == shares.first.bytesize
           raise TSS::ArgumentError, 'invalid shares, different byte lengths'
@@ -230,7 +207,7 @@ module TSS
       end
     end
 
-    def shares_have_valid_headers?(shares)
+    def shares_have_valid_headers!(shares)
       fh = Util.extract_share_header(shares.first)
       shares.each do |s|
         h = Util.extract_share_header(s)
@@ -240,7 +217,7 @@ module TSS
       end
     end
 
-    def shares_have_expected_length?(shares)
+    def shares_have_expected_length!(shares)
       shares.each do |s|
         unless s.bytesize > Splitter::SHARE_HEADER_STRUCT.size + 1
           raise TSS::ArgumentError, 'invalid shares, too short'
@@ -248,7 +225,7 @@ module TSS
       end
     end
 
-    def shares_meet_threshold_min?(shares)
+    def shares_meet_threshold_min!(shares)
       fh = Util.extract_share_header(shares.first)
       unless shares.size >= fh[:threshold]
         raise TSS::ArgumentError, 'invalid shares, fewer than threshold'
@@ -256,13 +233,13 @@ module TSS
     end
 
     def validate_all_shares(shares)
-      shares_have_valid_headers?(shares)
-      shares_have_same_bytesize?(shares)
-      shares_have_expected_length?(shares)
-      shares_meet_threshold_min?(shares)
+      shares_have_valid_headers!(shares)
+      shares_have_same_bytesize!(shares)
+      shares_have_expected_length!(shares)
+      shares_meet_threshold_min!(shares)
     end
 
-    def shares_bytes_have_valid_indexes?(shares_bytes)
+    def shares_bytes_have_valid_indexes!(shares_bytes)
       u = shares_bytes.collect do |s|
         raise TSS::ArgumentError, 'invalid shares, no index' if s[0].blank?
         raise TSS::ArgumentError, 'invalid shares, zero index' if s[0] == 0
@@ -274,13 +251,13 @@ module TSS
       end
     end
 
-    def share_combinations_mode_allowed?(hash_id)
+    def share_combinations_mode_allowed!(hash_id)
       unless Hasher.codes_without_none.include?(hash_id)
         raise TSS::ArgumentError, 'invalid options, combinations mode can only be used with hashed shares.'
       end
     end
 
-    def share_combinations_out_of_bounds?(shares, threshold, max_combinations = 1_000_000)
+    def share_combinations_out_of_bounds!(shares, threshold, max_combinations = 1_000_000)
       # Raise if the number of combinations is too high.
       # If this is not checked, the number of combinations can quickly grow into
       # numbers that cannot be calculated before the end of the universe.

data/lib/tss/hasher.rb

@@ -5,6 +5,10 @@ module TSS
                SHA256: { code: 2, bytesize: 32, hasher: Digest::SHA256 }
            }.freeze
 
+   # Lookup the Symbol key for a Hash with the code.
+   #
+   # @param code [Integer] the hash code to convert to a Symbol key
+   # @return [Symbol] the hash key Symbol
     def self.key_from_code(code)
       return nil unless Hasher.codes.include?(code)
       HASHES.each do |k, v|
@@ -12,40 +16,70 @@ module TSS
       end
     end
 
+    # Lookup the hash code for the hash matching hash_key.
+    #
+    # @param hash_key [Symbol, String] the hash key to convert to an Integer code
+    # @return [Integer] the hash key code
     def self.code(hash_key)
       HASHES[hash_key.upcase.to_sym][:code]
     end
 
-    # All valid hash codes, including NONE
+    # Lookup all valid hash codes, including NONE.
+    #
+    # @return [Array<Integer>] all hash codes including NONE
     def self.codes
       HASHES.collect do |_k, v|
         v[:code]
       end
     end
 
-    # All valid hash codes that actually do hashing
+    # All valid hash codes that actually do hashing, excluding NONE.
+    #
+    # @return [Array<Integer>] all hash codes excluding NONE
     def self.codes_without_none
       HASHES.collect do |_k, v|
         v[:code] if v[:code] > 0
       end.compact
     end
 
+    # Lookup the size in Bytes for a specific hash_key.
+    #
+    # @param hash_key [Symbol, String] the hash key to lookup
+    # @return [Integer] the size in Bytes for a specific hash_key
     def self.bytesize(hash_key)
       HASHES[hash_key.upcase.to_sym][:bytesize]
     end
 
+    # Return a hexdigest hash for a String using hash_key hash algorithm.
+    # Returns '' if hash_key == :NONE
+    #
+    # @param hash_key [Symbol, String] the hash key to use to hash a String
+    # @param str [String] the String to hash
+    # @return [String] the hex digest for str
     def self.hex_string(hash_key, str)
       hash_key = hash_key.upcase.to_sym
       return '' if hash_key == :NONE
       HASHES[hash_key][:hasher].send(:hexdigest, str)
     end
 
+    # Return a Byte String hash for a String using hash_key hash algorithm.
+    # Returns '' if hash_key == :NONE
+    #
+    # @param hash_key [Symbol, String] the hash key to use to hash a String
+    # @param str [String] the String to hash
+    # @return [String] the Byte String digest for str
     def self.byte_string(hash_key, str)
       hash_key = hash_key.upcase.to_sym
       return '' if hash_key == :NONE
       HASHES[hash_key][:hasher].send(:digest, str)
     end
 
+    # Return a Byte Array hash for a String using hash_key hash algorithm.
+    # Returns [] if hash_key == :NONE
+    #
+    # @param hash_key [Symbol, String] the hash key to use to hash a String
+    # @param str [String] the String to hash
+    # @return [Array<Integer>] the Byte Array digest for str
     def self.byte_array(hash_key, str)
       hash_key = hash_key.upcase.to_sym
       return [] if hash_key == :NONE

data/lib/tss/splitter.rb

@@ -42,57 +42,33 @@ module TSS
       .constrained(lteq: 255)
       .default(0)
 
-    # The `split` method takes a Hash of arguments. The following hash key args
-    # may be passed. Only `secret:` is required and the rest will be set to
-    # reasonable and secure defaults if unset. All args will be validated for
-    # correct type and values on object instantiation.
+    # To split a secret into a set of shares, the following
+    # procedure, or any equivalent method, is used:
     #
-    # `secret:` (required) takes a String (UTF-8 or US-ASCII encoding) with a
-    #           length between 1..65_534
+    #   This operation takes an octet string S, whose length is L octets, and
+    #   a threshold parameter M, and generates a set of N shares, any M of
+    #   which can be used to reconstruct the secret.
     #
-    # `threshold:` The number of shares (M) that will be required to recombine the
-    #              secret. Must be a value between 1..255 inclusive. Defaults to
-    #              a threshold of 3 shares.
+    #   The secret S is treated as an unstructured sequence of octets.  It is
+    #   not expected to be null-terminated.  The number of octets in the
+    #   secret may be anywhere from zero up to 65,534 (that is, two less than
+    #   2^16).
     #
-    # `num_shares:` The total number of shares (N) that will be created. Must be
-    #               a value between the `threshold` value (M) and 255 inclusive.
-    #               The upper limit is particular to the TSS algorithm used.
-    #               Defaults to generating 5 total shares.
+    #   The threshold parameter M is the number of shares that will be needed
+    #   to reconstruct the secret.  This value may be any number between one
+    #   and 255, inclusive.
     #
-    # `identifier:` A 0-16 bytes String limited to the characters 0-9, a-z, A-Z,
-    # the dash (-), the underscore (_), and the period (.). The identifier will
-    # be embedded in each the binary header of each share and should not reveal
-    # anything about the secret. It defaults to the value of `SecureRandom.hex(8)`
-    # which returns a random 16 Byte string which represents a Base10 decimal
-    # between 1 and 18446744073709552000.
+    #   The number of shares N that will be generated MUST be between the
+    #   threshold value M and 255, inclusive.  The upper limit is particular
+    #   to the TSS algorithm specified in this document.
     #
-    # `hash_alg:` The one-way hash algorithm that will be used to verify the
-    # secret returned by a later recombine operation is identical to what was
-    # split. This value will be concatenated with the secret prior to splitting.
-    # The valid hash algorithm values are `NONE`, `SHA1`, and `SHA256`. Defaults
-    # to `SHA256`. The use of `NONE` is discouraged as it does not allow those
-    # who are recombining the shares to verify if they have in fact recovered
-    # the correct secret.
-    #
-    # `pad_blocksize:` An integer representing the nearest multiple of Bytes
-    # to left pad the secret to. Defaults to not adding any padding (0). Padding
-    # is done with the "\u001F" character (decimal 31 in a Byte Array).
-    # Since TSS share data (minus the header) is essentially the same size as the
-    # original secret, padding smaller secrets may help mask the size of the
-    # contents from an attacker. Padding is not part of the RTSS spec so other
-    # TSS clients won't strip off the padding and may not validate correctly.
-    # If you need this interoperability you should probably pad the secret
-    # yourself prior to splitting it and leave the default zero-length pad in
-    # place. You would also need to manually remove the padding you added after
-    # the share is recombined.
-    #
-    # Calling `split` *must* return an Array of formatted shares or raise one of
-    # `TSS::Error` or `TSS::ArgumentError` exceptions if anything has gone wrong.
+    #   If the operation can not be completed successfully, then an error
+    #   code should be returned.
     #
     def split
-      secret_has_acceptable_encoding(secret)
-      secret_does_not_begin_with_padding_char(secret)
-      num_shares_not_less_than_threshold(threshold, num_shares)
+      secret_has_acceptable_encoding!(secret)
+      secret_does_not_begin_with_padding_char!(secret)
+      num_shares_not_less_than_threshold!(threshold, num_shares)
 
       # RTSS : Combine the secret with a hash digest before splitting. On recombine
       # the two will be separated again and the hash used to validate the
@@ -102,7 +78,7 @@ module TSS
       hashed_secret = Hasher.byte_array(hash_alg, secret)
       secret_bytes = Util.utf8_to_bytes(padded_secret) + hashed_secret
 
-      secret_bytes_is_smaller_than_max_size(secret_bytes)
+      secret_bytes_is_smaller_than_max_size!(secret_bytes)
 
       # For each share, a distinct Share Index is generated. Each Share
       # Index is an octet other than the all-zero octet. All of the Share
@@ -145,7 +121,7 @@ module TSS
       # build up a common binary struct header for all shares
       header = share_header(identifier, hash_alg, threshold, shares.first.length)
 
-      # create each binary share and return it.
+      # create each binary or human share and return it.
       shares.map! do |s|
         binary = (header + s.pack('C*')).force_encoding('ASCII-8BIT')
         # join with URL safe '~'
@@ -156,25 +132,25 @@ module TSS
 
     private
 
-    def secret_has_acceptable_encoding(secret)
+    def secret_has_acceptable_encoding!(secret)
       unless secret.encoding.name == 'UTF-8' || secret.encoding.name == 'US-ASCII'
         raise TSS::ArgumentError, "invalid secret, must be a UTF-8 or US-ASCII encoded String not '#{secret.encoding.name}'"
       end
     end
 
-    def secret_does_not_begin_with_padding_char(secret)
+    def secret_does_not_begin_with_padding_char!(secret)
       if secret.slice(0) == "\u001F"
         raise TSS::ArgumentError, 'invalid secret, first byte of secret is the reserved left-pad character (\u001F)'
       end
     end
 
-    def num_shares_not_less_than_threshold(threshold, num_shares)
+    def num_shares_not_less_than_threshold!(threshold, num_shares)
       if num_shares < threshold
         raise TSS::ArgumentError, "invalid num_shares, must be >= threshold (#{threshold})"
       end
     end
 
-    def secret_bytes_is_smaller_than_max_size(secret_bytes)
+    def secret_bytes_is_smaller_than_max_size!(secret_bytes)
       if secret_bytes.size >= 65_535
         raise TSS::ArgumentError, 'invalid secret, combined padded secret and hash are too large'
       end

data/lib/tss/tss.rb

@@ -1,15 +1,142 @@
+require 'digest'
+require 'base64'
+require 'securerandom'
+require 'binary_struct'
+require 'dry-types'
+require 'tss/blank'
+require 'tss/version'
+require 'tss/types'
+require 'tss/util'
+require 'tss/hasher'
+require 'tss/splitter'
+require 'tss/combiner'
+
+# Threshold Secret Sharing
+#
+# @author Glenn Rempe <glenn@rempe.us>
 module TSS
-  def self.split(args)
-    unless args.is_a?(Hash) && args.key?(:secret)
-      raise TSS::ArgumentError, 'TSS.split takes a Hash of arguments with at least a :secret key'
+  # An unexpected error has occurred.
+  class Error < StandardError; end
+
+  # An argument provided is of the wrong type, or has an invalid value.
+  class ArgumentError < TSS::Error; end
+
+  # A secret was attmepted to be recovered, but failed due to invalid shares.
+  class NoSecretError < TSS::Error; end
+
+  # A secret was attempted to be recovered, but failed due to an invalid verifier hash.
+  class InvalidSecretHashError < TSS::Error; end
+
+  # Threshold Secret Sharing (TSS) provides a way to generate N shares
+  # from a value, so that any M of those shares can be used to
+  # reconstruct the original value, but any M-1 shares provide no
+  # information about that value.  This method can provide shared access
+  # control on key material and other secrets that must be strongly
+  # protected.
+  #
+  # @param [Hash] opts the options to create a message with.
+  # @option opts [String] :secret takes a String (UTF-8 or US-ASCII encoding) with a length between 1..65_534
+  # @option opts [String] :threshold (3) The number of shares (M) that will be required to recombine the
+  #   secret. Must be a value between 1..255 inclusive. Defaults to a threshold of 3 shares.
+  # @option opts [String] :num_shares (5) The total number of shares (N) that will be created. Must be
+  #   a value between the `threshold` value (M) and 255 inclusive.
+  #   The upper limit is particular to the TSS algorithm used.
+  # @option opts [String] :identifier (SecureRandom.hex(8)) A 0-16 bytes String limited to the characters 0-9, a-z, A-Z,
+  #   the dash (-), the underscore (_), and the period (.). The identifier will
+  #   be embedded in each the binary header of each share and should not reveal
+  #   anything about the secret.
+  #
+  #   It defaults to the value of `SecureRandom.hex(8)`
+  #   which returns a random 16 Byte string which represents a Base10 decimal
+  #   between 1 and 18446744073709552000.
+  # @option opts [String] :hash_alg ('SHA256') The one-way hash algorithm that will be used to verify the
+  #   secret returned by a later recombine operation is identical to what was
+  #   split. This value will be concatenated with the secret prior to splitting.
+  #
+  #   The valid hash algorithm values are `NONE`, `SHA1`, and `SHA256`. Defaults
+  #   to `SHA256`. The use of `NONE` is discouraged as it does not allow those
+  #   who are recombining the shares to verify if they have in fact recovered
+  #   the correct secret.
+  # @option opts [String] :format ('binary') the format of the String share output, 'binary' or 'human'
+  # @option opts [String] :pad_blocksize (0) An integer representing the nearest multiple of Bytes
+  #   to left pad the secret to. Defaults to not adding any padding (0). Padding
+  #   is done with the "\u001F" character (decimal 31 in a Byte Array).
+  #
+  #   Since TSS share data (minus the header) is essentially the same size as the
+  #   original secret, padding smaller secrets may help mask the size of the
+  #   contents from an attacker. Padding is not part of the RTSS spec so other
+  #   TSS clients won't strip off the padding and may not validate correctly.
+  #
+  #   If you need this interoperability you should probably pad the secret
+  #   yourself prior to splitting it and leave the default zero-length pad in
+  #   place. You would also need to manually remove the padding you added after
+  #   the share is recombined, or instruct recipients to ignore it.
+  #
+  # @return [Array<String>] an Array of String shares
+  # @raise [TSS::ArgumentError] if the options Types or Values are invalid
+  def self.split(opts)
+    unless opts.is_a?(Hash) && opts.key?(:secret)
+      raise TSS::ArgumentError, 'TSS.split takes a Hash of options with at least a :secret key'
+    end
+
+    begin
+      TSS::Splitter.new(opts).split
+    rescue Dry::Types::ConstraintError => e
+      raise TSS::ArgumentError, e.message
     end
-    TSS::Splitter.new(args).split
   end
 
-  def self.combine(args)
-    unless args.is_a?(Hash) && args.key?(:shares)
-      raise TSS::ArgumentError, 'TSS.combine takes a Hash of arguments with at least a :shares key'
+  # The reconstruction, or combining, operation reconstructs the secret from a
+  # set of valid shares where the number of shares is >= the threshold when the
+  # secret was initially split. All options are provided in a single Hash:
+  #
+  # @param [Hash] opts the options to create a message with.
+  # @option opts [Array<String>] :shares an Array of String shares to try to recombine into a secret
+  # @option opts [String] :select_by ('first') the method to use for selecting
+  #   shares from the Array if more then threshold shares are provided. Can be
+  #   'first', 'sample', or 'combinations'.
+  #
+  #   If the number of shares provided as input to the secret
+  #   reconstruction operation is greater than the threshold M, then M
+  #   of those shares are selected for use in the operation.  The method
+  #   used to select the shares can be chosen using the following values:
+  #
+  #   `first` : If X shares are required by the threshold and more than X
+  #   shares are provided, then the first X shares in the Array of shares provided
+  #   will be used. All others will be discarded and the operation will fail if
+  #   those selected shares cannot recreate the secret.
+  #
+  #   `sample` : If X shares are required by the threshold and more than X
+  #   shares are provided, then X shares will be randomly selected from the Array
+  #   of shares provided.  All others will be discarded and the operation will
+  #   fail if those selected shares cannot recreate the secret.
+  #
+  #   `combinations` : If X shares are required, and more than X shares are
+  #   provided, then all possible combinations of the threshold number of shares
+  #   will be tried to see if the secret can be recreated.
+  #   This flexibility comes with a cost. All combinations of `threshold` shares
+  #   must be generated. Due to the math associated with combinations it is possible
+  #   that the system would try to generate a number of combinations that could never
+  #   be generated or processed in many times the life of the Universe. This option
+  #   can only be used if the possible combinations for the number of shares and the
+  #   threshold needed to reconstruct a secret result in a number of combinations
+  #   that is small enough to have a chance at being processed. If the number
+  #   of combinations will be too large then the an Exception will be raised before
+  #   processing has started.
+  #
+  # @return [Hash] a Hash containing the ':secret' and other metadata
+  # @raise [TSS::NoSecretError] if the secret cannot be re-created from the shares provided
+  # @raise [TSS::InvalidSecretHashError] if the embedded hash of the secret does not match the hash of the recreated secret
+  # @raise [TSS::ArgumentError] if the options Types or Values are invalid
+  def self.combine(opts)
+    unless opts.is_a?(Hash) && opts.key?(:shares)
+      raise TSS::ArgumentError, 'TSS.combine takes a Hash of options with at least a :shares key'
+    end
+
+    begin
+      TSS::Combiner.new(opts).combine
+    rescue Dry::Types::ConstraintError => e
+      raise TSS::ArgumentError, e.message
     end
-    TSS::Combiner.new(args).combine
   end
 end

data/lib/tss/util.rb

@@ -1,6 +1,9 @@
-# Common utility and math functions
 module TSS
+  # Common utility, math, and conversion functions.
   module Util
+    # The regex to match against human style shares
+    HUMAN_SHARE_RE = /^tss~v1~*[a-zA-Z0-9\.\-\_]{0,16}~[0-9]{1,3}~([a-zA-Z0-9\-\_]+\={0,2})$/
+
     # The EXP table.  The elements are to be read from top to
     # bottom and left to right.  For example, EXP[0] is 0x01, EXP[8] is
     # 0x1a, and so on. Note that the EXP[255] entry is present only as a
@@ -75,14 +78,23 @@ module TSS
          103,  74,  237,  222,  197,   49,  254,   24,
          13,   99,  140,  128,  192,  247,  112,    7].freeze
 
+    # GF(256) Addition
     # The addition operation returns the Bitwise
     # Exclusive OR (XOR) of its operands.
+    #
+    # @param a [Integer] a single Integer
+    # @param b [Integer] a single Integer
+    # @return [Integer] a GF(256) SUM of a and b
     def self.gf256_add(a, b)
       a ^ b
     end
 
-    # The subtraction operation is identical, because the field has
-    # characteristic two.
+    # The subtraction operation is identical to GF(256) addition, because the
+    # field has characteristic two.
+    #
+    # @param a [Integer] a single Integer
+    # @param b [Integer] a single Integer
+    # @return [Integer] a GF(256) subtraction of a and b
     def self.gf256_sub(a, b)
       gf256_add(a, b)
     end
@@ -91,6 +103,10 @@ module TSS
     # proceeds as follows.  If either X or Y is equal to 0x00, then the
     # operation returns 0x00.  Otherwise, the value EXP[ (LOG[X] + LOG[Y])
     # modulo 255] is returned.
+    #
+    # @param x [Integer] a single Integer
+    # @param y [Integer] a single Integer
+    # @return [Integer] a GF(256) multiplication of x and y
     def self.gf256_mul(x, y)
       return 0 if x == 0 || y == 0
       EXP[(LOG[x] + LOG[y]) % 255]
@@ -101,16 +117,18 @@ module TSS
     # the operation returns 0x00.  If Y is equal to 0x00, then the input is
     # invalid, and an error condition occurs.  Otherwise, the value
     # EXP[(LOG[X] - LOG[Y]) modulo 255] is returned.
+    #
+    # @param x [Integer] a single Integer
+    # @param y [Integer] a single Integer
+    # @return [Integer] a GF(256) division of x divided by y
+    # @raise [TSS::Error] if an attempt to divide by zero is tried
     def self.gf256_div(x, y)
       return 0 if x == 0
       raise TSS::Error, 'divide by zero' if y == 0
       EXP[(LOG[x] - LOG[y]) % 255]
     end
 
-    # Share generation Functions
-    ############################
-
-    # We first define how to share a single octet.
+    # Share generation Function
     #
     # The function f takes as input a single octet X that is not equal to
     # 0x00, and an array A of M octets, and returns a single octet.  It is
@@ -124,6 +142,11 @@ module TSS
     # the successive values of X^i used in the computation of the function
     # f can be computed by multiplying a value by X once for each term in
     # the summation.
+    #
+    # @param x [Integer] a single Integer
+    # @param bytes [Array<Integer>] an Array of Integers
+    # @return [Integer] a single Integer
+    # @raise [TSS::Error] if the index value for the share is zero
     def self.f(x, bytes)
       raise TSS::Error, 'invalid share index value, cannot be 0' if x == 0
       y = 0
@@ -137,9 +160,8 @@ module TSS
       y
     end
 
-    # Secret Reconstruction Functions
-    # ###############################
-
+    # Secret Reconstruction Function
+    #
     # We define the function L_i (for i from 0 to M-1, inclusive) that
     # takes as input an array U of M pairwise distinct octets, and is
     # defined as
@@ -154,6 +176,9 @@ module TSS
     # expression is never equal to zero because U[i] is not equal to U[j]
     # whenever i is not equal to j.
     #
+    # @param i [Integer] a single Integer
+    # @param u [Array<Integer>] an Array of Integers
+    # @return [Integer] a single Integer
     def self.basis_poly(i, u)
       prod = 1
 
@@ -165,6 +190,8 @@ module TSS
       prod
     end
 
+    # Secret Reconstruction Function
+    #
     # We denote the interpolation function as I. This function takes as
     # input two arrays U and V, each consisting of M octets, and returns a
     # single octet; it is defined as:
@@ -172,6 +199,9 @@ module TSS
     #   I(U, V) =  GF_SUM  L_i(U) (*) V[i].
     #              i=0,M-1
     #
+    # @param u [Array<Integer>] an Array of Integers
+    # @param v [Array<Integer>] an Array of Integers
+    # @return [Integer] a single Integer
     def self.lagrange_interpolation(u, v)
       sum = 0
 
@@ -182,25 +212,37 @@ module TSS
       sum
     end
 
-    # Conversion Functions
-    ######################
-
-    # String to Byte Array
+    # Convert a UTF-8 String to an Array of Bytes
+    #
+    # @param str [String] a UTF-8 String to convert
+    # @return [Array<Integer>] an Array of Integer Bytes
     def self.utf8_to_bytes(str)
       str.bytes.to_a
     end
 
-    # Byte Array to String
+    # Convert an Array of Bytes to a UTF-8 String
+    #
+    # @param bytes [Array<Integer>] an Array of Bytes to convert
+    # @return [String] a UTF-8 String
     def self.bytes_to_utf8(bytes)
       bytes.pack('C*').force_encoding('utf-8')
     end
 
+    # Convert an Array of Bytes to a hex String
+    #
+    # @param bytes [Array<Integer>] an Array of Bytes to convert
+    # @return [String] a hex String
     def self.bytes_to_hex(bytes)
       hex = ''
       bytes.each { |b| hex += sprintf('%02x', b).upcase }
       hex
     end
 
+    # Convert a hex String to an Array of Bytes
+    #
+    # @param str [String] a hex String to convert
+    # @return [Array<Integer>] an Array of Integer Bytes
+    # @raise [TSS::Error] if the hex value is not an even length
     def self.hex_to_bytes(str)
       # clone so we don't destroy the original string passed in by slicing it.
       strc = str.clone
@@ -212,16 +254,28 @@ module TSS
       bytes
     end
 
+    # Convert a hex String to a UTF-8 String
+    #
+    # @param hex [String] a hex String to convert
+    # @return [String] a UTF-8 String
     def self.hex_to_utf8(hex)
       bytes_to_utf8(hex_to_bytes(hex))
     end
 
+    # Convert a UTF-8 String to a hex String
+    #
+    # @param str [String] a UTF-8 String to convert
+    # @return [String] a hex String
     def self.utf8_to_hex(str)
       bytes_to_hex(utf8_to_bytes(str))
     end
 
-    # String Helpers
-
+    # Left pad a String with pad_char in multiples of byte_multiple
+    #
+    # @param byte_multiple [Integer] pad in blocks of this size
+    # @param input_string [String] the String to pad
+    # @param pad_char [String] the String to pad with
+    # @return [String] a padded String
     def self.left_pad(byte_multiple, input_string, pad_char = "\u001F")
       return input_string if byte_multiple == 0
       pad_length = byte_multiple - (input_string.length % byte_multiple)
@@ -229,16 +283,44 @@ module TSS
       (pad_char * pad_length) + input_string
     end
 
-    # Binary Header Helpers
+    # Constant time string comparison.
+    #   Extracted from Rack::Utils
+    #   https://github.com/rack/rack/blob/master/lib/rack/utils.rb
+    #
+    #   NOTE: the values compared should be of fixed length, such as strings
+    #   that have already been processed by HMAC. This should not be used
+    #   on variable length plaintext strings because it could leak length info
+    #   via timing attacks. The user provided value should always be passed
+    #   in as the second parameter so as not to leak info about the secret.
+    #
+    # @param a [String] the private value
+    # @param b [String] the user provided value
+    # @return [true, false] whether the strings match or not
+    def self.secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      l = a.unpack("C*")
+
+      r, i = 0, -1
+      b.each_byte { |v| r |= v ^ l[i+=1] }
+      r == 0
+    end
 
+    # Extract the header data from a binary share.
+    # Extra "\x00" padding in the identifier will be removed.
+    #
+    # @param share [String] a binary octet share
+    # @return [Hash] header attributes
     def self.extract_share_header(share)
       h = Splitter::SHARE_HEADER_STRUCT.decode(share)
       h[:identifier] = h[:identifier].delete("\x00")
       return h
     end
 
-    # Math Helpers
-
+    # Calculate the factorial for an Integer.
+    #
+    # @param n [Integer] the Integer to calculate for
+    # @return [Integer] the factorial of n
     def self.factorial(n)
       (1..n).reduce(:*) || 1
     end
@@ -246,19 +328,25 @@ module TSS
     # Calculate the number of combinations possible
     # for a given number of shares and threshold.
     #
-    # See : http://www.wolframalpha.com/input/?i=20+choose+5
-    # See : http://www.mathsisfun.com/combinatorics/combinations-permutations-calculator.html (Set balls, 20, 5, no, no) == 15504
-    # See : http://www.mathsisfun.com/combinatorics/combinations-permutations.html
-    # See : https://jdanger.com/calculating-factorials-in-ruby.html
-    # See : http://chriscontinanza.com/2010/10/29/Array.html
-    # See : http://stackoverflow.com/questions/2434503/ruby-factorial-function
+    # * http://www.wolframalpha.com/input/?i=20+choose+5
+    # * http://www.mathsisfun.com/combinatorics/combinations-permutations-calculator.html (Set balls, 20, 5, no, no) == 15504
+    # * http://www.mathsisfun.com/combinatorics/combinations-permutations.html
+    # * https://jdanger.com/calculating-factorials-in-ruby.html
+    # * http://chriscontinanza.com/2010/10/29/Array.html
+    # * http://stackoverflow.com/questions/2434503/ruby-factorial-function
     #
-    # n is the total number of shares
-    # r is the threshold number of shares
+    # @param n [Integer] the total number of shares
+    # @param r [Integer] the threshold number of shares
+    # @return [Integer] the number of possible combinations
     def self.calc_combinations(n, r)
       factorial(n) / (factorial(r) * factorial(n - r))
     end
 
+    # Converts an Integer into a delimiter separated String.
+    #
+    # @param n [Integer] an Integer to convert
+    # @param delimiter [String] the String to delimit n in three Integer groups
+    # @return [String] the object converted into a comma separated String.
     def self.int_commas(n, delimiter = ',')
       n.to_s.reverse.gsub(%r{([0-9]{3}(?=([0-9])))}, "\\1#{delimiter}").reverse
     end

data/lib/tss/version.rb

@@ -1,3 +1,3 @@
 module TSS
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.1.1'.freeze
 end

data/lib/tss.rb

@@ -1,14 +1 @@
-require 'digest'
-require 'base64'
-require 'securerandom'
-require 'binary_struct'
-require 'dry-types'
 require 'tss/tss'
-require 'tss/blank'
-require 'tss/version'
-require 'tss/types'
-require 'tss/errors'
-require 'tss/util'
-require 'tss/hasher'
-require 'tss/splitter'
-require 'tss/combiner'

data/tss.gemspec

@@ -9,6 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Glenn Rempe']
   spec.email         = ['glenn@rempe.us']
 
+  spec.required_ruby_version = '>= 2.1.0'
+
   cert = File.expand_path('~/.gem-certs/gem-private_key_grempe.pem')
   if File.exist?(cert)
     spec.signing_key = cert

data.tar.gz.sig

@@ -1,4 +1,2 @@
-k@2&��atr�'������@:��J
-􍉩
-Y�*�|�F�G�G�NA
-����5u�g�����w�Td�~�q
��<�E����}Y�Jr�Z�P��r<,��#�#ೲ���ņ��c�nӻn����b5��Hxw;�����V��q� '�ౝ���cW��#�Ea�*E<�U-V���~��A����Иj%�~H�I_���'D
+��!�x^��9�(`�eܝ!���W�YJ
+�,�A

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tss
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Glenn Rempe
@@ -30,7 +30,7 @@ cert_chain:
   zieXiXZSAojfFx9g91fKdIrlPbInHU/BaCxXSLBwvOM0drE+c2ue9X8gB55XAhzX
   37oBiw==
   -----END CERTIFICATE-----
-date: 2016-04-12 00:00:00.000000000 Z
+date: 2016-04-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-types
@@ -171,6 +171,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - ".travis.yml"
+- ".yardopts"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -186,7 +187,6 @@ files:
 - lib/tss/blank.rb
 - lib/tss/cli.rb
 - lib/tss/combiner.rb
-- lib/tss/errors.rb
 - lib/tss/hasher.rb
 - lib/tss/splitter.rb
 - lib/tss/tss.rb
@@ -206,7 +206,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/tss/errors.rb

@@ -1,4 +0,0 @@
-module TSS
-  class Error < RuntimeError; end
-  class ArgumentError < Error; end
-end