tss 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4a6856a5740bb924091f7d3c11709a0ca5a85f8b
-  data.tar.gz: 238fd08ac664b9518cfe5923261294808be59955
+  metadata.gz: e448b355558f4f493400bac55a51fd14a8c56bf3
+  data.tar.gz: 537024e64cf91c9394784d76d9df61347add2041
 SHA512:
-  metadata.gz: d651a525d7b9c8869c720df9178b48b9c1502f5f2e3e1cdf160dcd68a9865f0534fa01bf6ef28831bcedb72a3bd886c536e74466f9d4a707f3d361e2da9bc411
-  data.tar.gz: 8e1b706a13ef836f61ac5b94edae245e3e2578a80f736f13c146dbdab0efe43eed5d01f4a6983fa8fd8434909bf7fa1140f2ddce23d47fe375fa81bae1413c5a
+  metadata.gz: b69d52a5340fda8078e46e1ed95dc4c5a6e4ffbb54b5ac0295dce9fc2633decacf61a7616dff3c838772e3bb9e97be110d6a819a07fbf04d7f4ef0e8cfac9491
+  data.tar.gz: 5cc4fa4acc4e920dda21772432512da25b46bf9a16ac960496e0eb8cd0c0b2a3b5da979e4863e5571d0dcaa3962202ee9ec8bc3c98eb589b05ef8e8f5e653a0b

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## v0.3.0 (9/24/2016)
+
+* Breaking change, identifier cannot be an empty string
+* Much greater coverage of functions with Contracts
+* Related documentation updates
+
 ## v0.2.0 (9/23/2016)
 
 * clone the shares object passed to TSS.combine to prevent modification

data/README.md

@@ -57,8 +57,8 @@ command line or Ruby, with the default `3 out of 5` secret sharing.
 ### Command Line Interface (CLI)
 
 ```sh
-$ echo 'secret unicode characters ½ ♥ 💩' | bundle exec bin/tss split -O /tmp/shares.txt
-$ bundle exec bin/tss combine -I /tmp/shares.txt
+$ echo 'secret unicode characters ½ ♥ 💩' | tss split -O /tmp/shares.txt
+$ tss combine -I /tmp/shares.txt
 
 RECOVERED SECRET METADATA
 *************************
@@ -253,7 +253,7 @@ cautioned that this method may leave command history which may contain your
 secret.
 
 ```text
-echo 'a secret' | bundle exec bin/tss split -O /tmp/shares.txt
+echo 'a secret' | tss split -O /tmp/shares.txt
 ```
 
 **Example : `--input-file`**
@@ -263,7 +263,7 @@ cautioned that storing the secret on a filesystem may expose you to certain
 attacks since it can be hard to fully erase files once written.
 
 ```text
-$ bundle exec bin/tss split -I /tmp/secret.txt
+$ tss split -I /tmp/secret.txt
 tss~v1~3f784d9d04dff796~3~M2Y3ODRkOWQwNGRmZjc5NgIDACsBvAVAo1dH3QrsYl0S30j2VVTu6dZLRe9EEk6zLtPTwZNYk-t1e4SAA41D
 tss~v1~3f784d9d04dff796~3~M2Y3ODRkOWQwNGRmZjc5NgIDACsCMfy6YlI-CQrd-l93Xtw8YqOWSP5ToolKTaZyO2fPYzceaaVmB30ycdVr
 tss~v1~3f784d9d04dff796~3~M2Y3ODRkOWQwNGRmZjc5NgIDACsD4IDasmAapmVFkuYPMvuavCtXiJgPZsaBHglGm4FU_U2rGZzfapRk-ZNN
@@ -279,7 +279,7 @@ in the command shell history or in a file on a filesystem that is hard to
 erase securely. It does not protect you from simple keylogger attacks though.
 
 ```text
-$ bundle exec bin/tss split
+$ tss split
 Enter your secret, enter a dot (.) on a line by itself to finish :
 secret >  the vault password is:
 secret >  V0ulT!
@@ -306,7 +306,7 @@ Here are some simple examples of using each:
 **Example : `STDIN`**
 
 ```text
-$ echo 'a secret' | bundle exec bin/tss split | bundle exec bin/tss combine
+$ echo 'a secret' | tss split | tss combine
 
 RECOVERED SECRET METADATA
 *************************
@@ -322,8 +322,8 @@ a secret
 **Example : `--input-file`**
 
 ```text
-$ echo 'a secret' | bundle exec bin/tss split -O /tmp/shares.txt
-$ bundle exec bin/tss combine -I /tmp/shares.txt
+$ echo 'a secret' | tss split -O /tmp/shares.txt
+$ tss combine -I /tmp/shares.txt
 
 RECOVERED SECRET METADATA
 *************************
@@ -351,7 +351,7 @@ tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoDsnUaZf94pMArKZL7jmavzk9Qa6
 tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoETCWwSGLHcutzGCLb1yOkH7i6MF7j2b0wr0ZsUh6LuBmx6FkN2MbTkTc=
 tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoFazXEwgGBilMwY7k7DtDR9qqG7mgigMJLmIVB70eAULfQJ89xbXbONF4=
 
-$ bundle exec bin/tss combine
+$ tss combine
 Enter shares, one per line, and a dot (.) on a line by itself to finish :
 share>  tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoBRjAH7wA0ncxJr3GliBqKxedf3bGaQH6AscuLqxtrKxxtxuC7A7a5Sqk=
 share>  tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoClWVu75w-XHhoUgkbV5XaJ11stZCB5Z8HTArpv4QsIYDBpNO9DHQTbQ4=
@@ -402,14 +402,13 @@ between `1-255` inclusive. The `num_shares` value must be
 greater-than-or-equal-to the `threshold` value. If you don't pass in
 these options they will be set to `threshold = 3` and `num_shares = 5` by default.
 
-The `identifier` is a `0-16` Byte String that will be embedded in
+The `identifier` is a `1-16` Byte String that will be embedded in
 each output share and should uniquely identify a secret. All shares output
 from the same secret splitting operation will have the same `identifier`. This
 value can be retrieved easily from a share header and should be assumed to be
 known to shareholders. Nothing that leaks information about the secret should
 be used as an `identifier`. If an `identifier` is not set, it will default
-to the output of `SecureRandom.hex(8)` which is 8 random hex bytes and
-16 characters long.
+to the output of `SecureRandom.hex(8)` which is 8 random hex bytes (16 characters).
 
 The `hash_alg` is a String that represents which cryptographic one-way
 hash function should be embedded in shares. The hash is used to verify

data/lib/tss/combiner.rb

@@ -53,6 +53,7 @@ module TSS
     #   The output string is returned (along with some metadata).
     #
     # rubocop:disable CyclomaticComplexity
+    Contract C::None => ({ :hash => C::Maybe[String], :hash_alg => C::Maybe[C::Enum['NONE', 'SHA1', 'SHA256']], :identifier => TSS::IdentifierArg, :process_time => C::Num, :secret => TSS::SecretArg, :threshold => TSS::ThresholdArg})
     def combine
       # unwrap 'human' shares into binary shares
       if all_shares_appear_human?(shares)
@@ -287,9 +288,9 @@ module TSS
     Contract C::ArrayOf[String] => C::Bool
     def validate_all_shares(shares)
       if shares_have_valid_headers!(shares) &&
-          shares_have_same_bytesize!(shares) &&
-          shares_have_expected_length!(shares) &&
-          shares_meet_threshold_min!(shares)
+         shares_have_same_bytesize!(shares) &&
+         shares_have_expected_length!(shares) &&
+         shares_meet_threshold_min!(shares)
         return true
       else
         return false

data/lib/tss/custom_contracts.rb

@@ -0,0 +1,66 @@
+module TSS
+
+  # Custom Contracts
+  # See : https://egonschiele.github.io/contracts.ruby/
+  class SecretArg
+    def self.valid? val
+      val.present? && val.is_a?(String) &&
+      val.length.between?(1,65502) &&
+      ['UTF-8', 'US-ASCII'].include?(val.encoding.name) &&
+      val.slice(0) != "\u001F"
+    end
+
+    def self.to_s
+      'must be a UTF-8 or US-ASCII String between 1 and 65,502 characters in length and must not begin with the padding char \u001F'
+    end
+  end
+
+  class ThresholdArg
+    def self.valid? val
+      val.present? &&
+      val.is_a?(Integer) &&
+      val.between?(1,255)
+    end
+
+    def self.to_s
+      'must be an Integer between 1 and 255'
+    end
+  end
+
+  class NumSharesArg
+    def self.valid? val
+      val.present? &&
+      val.is_a?(Integer) &&
+      val.between?(1,255)
+    end
+
+    def self.to_s
+      'must be an Integer between 1 and 255'
+    end
+  end
+
+  class IdentifierArg
+    def self.valid? val
+      val.present? &&
+      val.is_a?(String) &&
+      val.length.between?(1,16) &&
+      val =~ /^[a-zA-Z0-9\-\_\.]*$/i
+    end
+
+    def self.to_s
+      'must be a String between 1 and 16 characters in length limited to [a-z, A-Z, -, _, .]'
+    end
+  end
+
+  class PadBlocksizeArg
+    def self.valid? val
+      val.present? &&
+      val.is_a?(Integer) &&
+      val.between?(0,255)
+    end
+
+    def self.to_s
+      'must be an Integer between 0 and 255'
+    end
+  end
+end

data/lib/tss/hasher.rb

@@ -2,15 +2,18 @@ module TSS
   # Hasher is responsible for managing access to the various one-way hash
   # functions that can be used to validate a secret.
   class Hasher
+    include Contracts::Core
+    C = Contracts
+
     HASHES = { NONE: { code: 0, bytesize: 0, hasher: nil },
                SHA1: { code: 1, bytesize: 20, hasher: Digest::SHA1 },
-               SHA256: { code: 2, bytesize: 32, hasher: Digest::SHA256 }
-           }.freeze
+               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
+    # Lookup the Symbol key for a Hash with the code.
+    #
+    # @param code [Integer] the hash code to convert to a Symbol key
+    # @return [Symbol,nil] the hash key Symbol or nil if not found
+    Contract C::Int => C::Maybe[Symbol]
     def self.key_from_code(code)
       return nil unless Hasher.codes.include?(code)
       HASHES.each do |k, v|
@@ -22,6 +25,7 @@ module TSS
     #
     # @param hash_key [Symbol, String] the hash key to convert to an Integer code
     # @return [Integer] the hash key code
+    Contract C::Maybe[C::Enum['NONE', 'SHA1', 'SHA256'], C::Enum[:NONE, :SHA1, :SHA256]] => C::Maybe[C::Int]
     def self.code(hash_key)
       HASHES[hash_key.upcase.to_sym][:code]
     end
@@ -29,6 +33,7 @@ module TSS
     # Lookup all valid hash codes, including NONE.
     #
     # @return [Array<Integer>] all hash codes including NONE
+    Contract C::None => C::ArrayOf[C::Int]
     def self.codes
       HASHES.map do |_k, v|
         v[:code]
@@ -38,6 +43,7 @@ module TSS
     # All valid hash codes that actually do hashing, excluding NONE.
     #
     # @return [Array<Integer>] all hash codes excluding NONE
+    Contract C::None => C::ArrayOf[C::Int]
     def self.codes_without_none
       HASHES.map do |_k, v|
         v[:code] if v[:code] > 0
@@ -48,8 +54,9 @@ module TSS
     #
     # @param hash_key [Symbol, String] the hash key to lookup
     # @return [Integer] the size in Bytes for a specific hash_key
+    Contract C::Or[C::Enum['NONE', 'SHA1', 'SHA256'], C::Enum[:NONE, :SHA1, :SHA256]] => C::Int
     def self.bytesize(hash_key)
-      HASHES[hash_key.upcase.to_sym][:bytesize]
+      HASHES[hash_key.to_sym][:bytesize]
     end
 
     # Return a hexdigest hash for a String using hash_key hash algorithm.
@@ -58,6 +65,7 @@ module TSS
     # @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
+    Contract C::Or[C::Enum['NONE', 'SHA1', 'SHA256'], C::Enum[:NONE, :SHA1, :SHA256]], String => String
     def self.hex_string(hash_key, str)
       hash_key = hash_key.upcase.to_sym
       return '' if hash_key == :NONE
@@ -70,6 +78,7 @@ module TSS
     # @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
+    Contract C::Or[C::Enum['NONE', 'SHA1', 'SHA256'], C::Enum[:NONE, :SHA1, :SHA256]], String => String
     def self.byte_string(hash_key, str)
       hash_key = hash_key.upcase.to_sym
       return '' if hash_key == :NONE
@@ -82,6 +91,7 @@ module TSS
     # @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
+    Contract C::Or[C::Enum['NONE', 'SHA1', 'SHA256'], C::Enum[:NONE, :SHA1, :SHA256]], String => C::ArrayOf[C::Int]
     def self.byte_array(hash_key, str)
       hash_key = hash_key.upcase.to_sym
       return [] if hash_key == :NONE

data/lib/tss/splitter.rb

@@ -8,26 +8,15 @@ module TSS
 
     attr_reader :secret, :threshold, :num_shares, :identifier, :hash_alg, :format, :pad_blocksize
 
-    Contract ({ :secret => String, :threshold => C::Maybe[C::Int], :num_shares => C::Maybe[C::Int], :identifier => C::Maybe[String], :hash_alg => C::Maybe[C::Enum['NONE', 'SHA1', 'SHA256']], :format => C::Maybe[C::Enum['binary', 'human']], :pad_blocksize => C::Maybe[C::Int] }) => C::Any
+    Contract ({ :secret => TSS::SecretArg, :threshold => C::Maybe[TSS::ThresholdArg], :num_shares => C::Maybe[TSS::NumSharesArg], :identifier => C::Maybe[TSS::IdentifierArg], :hash_alg => C::Maybe[C::Enum['NONE', 'SHA1', 'SHA256']], :format => C::Maybe[C::Enum['binary', 'human']], :pad_blocksize => C::Maybe[TSS::PadBlocksizeArg] }) => C::Any
     def initialize(opts = {})
       @secret = opts.fetch(:secret)
-      raise TSS::ArgumentError, 'Invalid secret length. Must be between 1 and 65502' unless @secret.size.between?(1,65502)
-
       @threshold = opts.fetch(:threshold, 3)
-      raise TSS::ArgumentError, 'Invalid threshold size. Must be between 1 and 255' unless @threshold.between?(1,255)
-
       @num_shares = opts.fetch(:num_shares, 5)
-      raise TSS::ArgumentError, 'Invalid num_shares size. Must be between 1 and 255' unless @num_shares.between?(1,255)
-
       @identifier = opts.fetch(:identifier, SecureRandom.hex(8))
-      raise TSS::ArgumentError, 'Invalid identifier characters' unless @identifier =~ /^[a-zA-Z0-9\-\_\.]*$/i
-      raise TSS::ArgumentError, 'Invalid identifier size. Must be between 0 and 16' unless @identifier.size.between?(0,16)
-
       @hash_alg = opts.fetch(:hash_alg, 'SHA256')
       @format = opts.fetch(:format, 'human')
-
       @pad_blocksize = opts.fetch(:pad_blocksize, 0)
-      raise TSS::ArgumentError, 'Invalid pad_blocksize size. Must be between 0 and 255' unless @pad_blocksize.between?(0,255)
     end
 
     SHARE_HEADER_STRUCT = BinaryStruct.new([
@@ -60,9 +49,8 @@ module TSS
     #   If the operation can not be completed successfully, then an error
     #   code should be returned.
     #
+    Contract C::None => C::ArrayOf[String]
     def split
-      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
@@ -129,35 +117,11 @@ module TSS
         human = ['tss', 'v1', identifier, threshold, Base64.urlsafe_encode64(binary)].join('~')
         format == 'binary' ? binary : human
       end
-    end
-
-    private
 
-    # The secret must be encoded with UTF-8 of US-ASCII or it is invalid.
-    #
-    # @param secret [String] a secret String
-    # @return [true] returns true if acceptable encoding
-    # @raise [TSS::ArgumentError] if invalid
-    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}'"
-      else
-        return true
-      end
+      return shares
     end
 
-    # The secret must not being with the padding character or it is invalid.
-    #
-    # @param secret [String] a secret String
-    # @return [true] returns true if String does not begin with padding character
-    # @raise [TSS::ArgumentError] if invalid
-    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)'
-      else
-        return true
-      end
-    end
+    private
 
     # The num_shares must be greater than or equal to the threshold or it is invalid.
     #
@@ -165,6 +129,7 @@ module TSS
     # @param num_shares [Integer] the num_shares value
     # @return [true] returns true if num_shares is >= threshold
     # @raise [TSS::ArgumentError] if invalid
+    Contract TSS::ThresholdArg, TSS::NumSharesArg => C::Bool
     def num_shares_not_less_than_threshold!(threshold, num_shares)
       if num_shares < threshold
         raise TSS::ArgumentError, "invalid num_shares, must be >= threshold (#{threshold})"
@@ -179,6 +144,7 @@ module TSS
     # @param secret_bytes [Array<Integer>] the Byte Array containing the secret
     # @return [true] returns true if num_shares is >= threshold
     # @raise [TSS::ArgumentError] if invalid
+    Contract C::ArrayOf[C::Int] => C::Bool
     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'
@@ -194,6 +160,7 @@ module TSS
     # @param threshold [Integer] the threshold value
     # @param share_len [Integer] the length of the share in Bytes
     # @return [String] returns an octet String of Bytes containing the binary header
+    Contract TSS::IdentifierArg, C::Maybe[C::Enum['NONE', 'SHA1', 'SHA256']], TSS::ThresholdArg, C::Int => String
     def share_header(identifier, hash_alg, threshold, share_len)
       SHARE_HEADER_STRUCT.encode(identifier: identifier,
                                  hash_id: Hasher.code(hash_alg),

data/lib/tss/tss.rb

@@ -5,6 +5,7 @@ require 'binary_struct'
 require 'contracts'
 require 'tss/blank'
 require 'tss/version'
+require 'tss/custom_contracts'
 require 'tss/util'
 require 'tss/hasher'
 require 'tss/splitter'
@@ -14,6 +15,9 @@ require 'tss/combiner'
 #
 # @author Glenn Rempe <glenn@rempe.us>
 module TSS
+  include Contracts::Core
+  C = Contracts
+
   # An unexpected error has occurred.
   class Error < StandardError; end
 
@@ -35,17 +39,17 @@ module TSS
   #
   # @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
+  # @option opts [Integer] :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
+  # @option opts [Integer] :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,
+  # @option opts [String] :identifier (SecureRandom.hex(8)) A 1-16 byte 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)`
+  #   If the arg is nil 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
@@ -57,7 +61,7 @@ module TSS
   #   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
+  # @option opts [Integer] :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).
   #
@@ -72,17 +76,10 @@ module TSS
   #   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
+  # @raise [ParamContractError, TSS::ArgumentError] if the options Types or Values are invalid
+  Contract ({ :secret => TSS::SecretArg, :threshold => C::Maybe[TSS::ThresholdArg], :num_shares => C::Maybe[TSS::NumSharesArg], :identifier => C::Maybe[TSS::IdentifierArg], :hash_alg => C::Maybe[C::Enum['NONE', 'SHA1', 'SHA256']], :format => C::Maybe[C::Enum['binary', 'human']], :pad_blocksize => C::Maybe[TSS::PadBlocksizeArg] }) => C::ArrayOf[String]
   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 ParamContractError => e
-      raise TSS::ArgumentError, e.message
-    end
+    TSS::Splitter.new(opts).split
   end
 
   # The reconstruction, or combining, operation reconstructs the secret from a
@@ -126,16 +123,9 @@ module TSS
   # @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
+  # @raise [ParamContractError, TSS::ArgumentError] if the options Types or Values are invalid
+  Contract ({ :shares => C::ArrayOf[String], :select_by => C::Maybe[C::Enum['first', 'sample', 'combinations']] }) => ({ :hash => C::Maybe[String], :hash_alg => C::Enum['NONE', 'SHA1', 'SHA256'], :identifier => TSS::IdentifierArg, :process_time => C::Num, :secret => TSS::SecretArg, :threshold => TSS::ThresholdArg})
   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 ParamContractError => e
-      raise TSS::ArgumentError, e.message
-    end
+    TSS::Combiner.new(opts).combine
   end
 end

data/lib/tss/util.rb

@@ -1,6 +1,9 @@
 module TSS
   # Common utility, math, and conversion functions.
   module Util
+    include Contracts::Core
+    C = Contracts
+
     # 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})$/
 
@@ -216,6 +219,7 @@ module TSS
     #
     # @param str [String] a UTF-8 String to convert
     # @return [Array<Integer>] an Array of Integer Bytes
+    Contract String => C::ArrayOf[C::Int]
     def self.utf8_to_bytes(str)
       str.bytes.to_a
     end
@@ -224,6 +228,7 @@ module TSS
     #
     # @param bytes [Array<Integer>] an Array of Bytes to convert
     # @return [String] a UTF-8 String
+    Contract C::ArrayOf[C::Int] => String
     def self.bytes_to_utf8(bytes)
       bytes.pack('C*').force_encoding('utf-8')
     end
@@ -232,6 +237,7 @@ module TSS
     #
     # @param bytes [Array<Integer>] an Array of Bytes to convert
     # @return [String] a hex String
+    Contract C::ArrayOf[C::Int] => String
     def self.bytes_to_hex(bytes)
       hex = ''
       bytes.each { |b| hex += sprintf('%02x', b) }
@@ -242,6 +248,7 @@ module TSS
     #
     # @param str [String] a hex String to convert
     # @return [Array<Integer>] an Array of Integer Bytes
+    Contract String => C::ArrayOf[C::Int]
     def self.hex_to_bytes(str)
       [str].pack('H*').unpack('C*')
     end
@@ -250,6 +257,7 @@ module TSS
     #
     # @param hex [String] a hex String to convert
     # @return [String] a UTF-8 String
+    Contract String => String
     def self.hex_to_utf8(hex)
       bytes_to_utf8(hex_to_bytes(hex))
     end
@@ -258,6 +266,7 @@ module TSS
     #
     # @param str [String] a UTF-8 String to convert
     # @return [String] a hex String
+    Contract String => String
     def self.utf8_to_hex(str)
       bytes_to_hex(utf8_to_bytes(str))
     end
@@ -268,6 +277,7 @@ module TSS
     # @param input_string [String] the String to pad
     # @param pad_char [String] the String to pad with
     # @return [String] a padded String
+    Contract C::Int, String, String => 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)
@@ -288,6 +298,7 @@ module TSS
     # @param a [String] the private value
     # @param b [String] the user provided value
     # @return [true, false] whether the strings match or not
+    Contract String, String => C::Bool
     def self.secure_compare(a, b)
       return false unless a.bytesize == b.bytesize
 
@@ -303,6 +314,7 @@ module TSS
     #
     # @param share [String] a binary octet share
     # @return [Hash] header attributes
+    Contract String => Hash
     def self.extract_share_header(share)
       h = Splitter::SHARE_HEADER_STRUCT.decode(share)
       h[:identifier] = h[:identifier].delete("\x00")
@@ -313,6 +325,7 @@ module TSS
     #
     # @param n [Integer] the Integer to calculate for
     # @return [Integer] the factorial of n
+    Contract C::Int => C::Int
     def self.factorial(n)
       (1..n).reduce(:*) || 1
     end
@@ -330,6 +343,7 @@ module TSS
     # @param n [Integer] the total number of shares
     # @param r [Integer] the threshold number of shares
     # @return [Integer] the number of possible combinations
+    Contract C::Int, C::Int => C::Int
     def self.calc_combinations(n, r)
       factorial(n) / (factorial(r) * factorial(n - r))
     end
@@ -339,6 +353,7 @@ module TSS
     # @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.
+    Contract C::Int, String => 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.2.0'.freeze
+  VERSION = '0.3.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tss
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Glenn Rempe
@@ -30,7 +30,7 @@ cert_chain:
   zieXiXZSAojfFx9g91fKdIrlPbInHU/BaCxXSLBwvOM0drE+c2ue9X8gB55XAhzX
   37oBiw==
   -----END CERTIFICATE-----
-date: 2016-09-23 00:00:00.000000000 Z
+date: 2016-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sysrandom
@@ -238,6 +238,7 @@ files:
 - lib/tss/cli_split.rb
 - lib/tss/cli_version.rb
 - lib/tss/combiner.rb
+- lib/tss/custom_contracts.rb
 - lib/tss/hasher.rb
 - lib/tss/splitter.rb
 - lib/tss/tss.rb