tss 0.1.0

data/lib/tss/errors.rb

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

data/lib/tss/hasher.rb

@@ -0,0 +1,55 @@
+module TSS
+  class Hasher
+    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
+
+    def self.key_from_code(code)
+      return nil unless Hasher.codes.include?(code)
+      HASHES.each do |k, v|
+        return k if v[:code] == code
+      end
+    end
+
+    def self.code(hash_key)
+      HASHES[hash_key.upcase.to_sym][:code]
+    end
+
+    # All valid hash codes, including NONE
+    def self.codes
+      HASHES.collect do |_k, v|
+        v[:code]
+      end
+    end
+
+    # All valid hash codes that actually do hashing
+    def self.codes_without_none
+      HASHES.collect do |_k, v|
+        v[:code] if v[:code] > 0
+      end.compact
+    end
+
+    def self.bytesize(hash_key)
+      HASHES[hash_key.upcase.to_sym][:bytesize]
+    end
+
+    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
+
+    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
+
+    def self.byte_array(hash_key, str)
+      hash_key = hash_key.upcase.to_sym
+      return [] if hash_key == :NONE
+      HASHES[hash_key][:hasher].send(:digest, str).unpack('C*')
+    end
+  end
+end

data/lib/tss/splitter.rb

@@ -0,0 +1,190 @@
+module TSS
+  class Splitter < Dry::Types::Struct
+    include Util
+
+    SHARE_HEADER_STRUCT = BinaryStruct.new([
+                     'a16', :identifier,  # String, 16 Bytes, arbitrary binary string (null padded, count is width)
+                     'C', :hash_id,
+                     'C', :threshold,
+                     'n', :share_len
+                    ])
+
+    # dry-types
+    constructor_type(:schema)
+
+    attribute :secret, Types::Strict::String
+      .constrained(min_size: 1)
+
+    attribute :threshold, Types::Coercible::Int
+      .constrained(gteq: 1)
+      .constrained(lteq: 255)
+      .default(3)
+
+    attribute :num_shares, Types::Coercible::Int
+      .constrained(gteq: 1)
+      .constrained(lteq: 255)
+      .default(5)
+
+    attribute :identifier, Types::Strict::String
+      .constrained(min_size: 0)
+      .constrained(max_size: 16)
+      .default { SecureRandom.hex(8) }
+      .constrained(format: /^[a-zA-Z0-9\-\_\.]*$/i) # 0 or more of these chars
+
+    attribute :hash_alg, Types::Strict::String.enum('NONE', 'SHA1', 'SHA256')
+      .default('SHA256')
+
+    attribute :format, Types::Strict::String.enum('binary', 'human')
+      .default('binary')
+
+    attribute :pad_blocksize, Types::Coercible::Int
+      .constrained(gteq: 0)
+      .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.
+    #
+    # `secret:` (required) takes a String (UTF-8 or US-ASCII encoding) with a
+    #           length between 1..65_534
+    #
+    # `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.
+    #
+    # `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.
+    #
+    # `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.
+    #
+    # `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.
+    #
+    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
+      # the two will be separated again and the hash used to validate the
+      # correct secret was returned. secret || hash(secret). You can also
+      # optionally pad the secret first.
+      padded_secret = Util.left_pad(pad_blocksize, secret)
+      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)
+
+      # 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
+      # Indexes used during a share generation process MUST be distinct.
+      # Each share is initialized to the Share Index associated with that
+      # share.
+      shares = []
+      (1..num_shares).each { |n| shares << [n] }
+
+      # For each octet of the secret, the following steps are performed.
+      #
+      # An array A of M octets is created, in which the array element A[0]
+      # contains the octet of the secret, and the array elements A[1],
+      # ..., A[M-1] contain octets that are selected independently and
+      # uniformly at random.
+      #
+      # For each share, the value of f(X,A) is
+      # computed, where X is the Share Index of the share, and the
+      # resulting octet is appended to the share.
+      #
+      # After the procedure is done, each share contains one more octet than
+      # does the secret.  The share format can be illustrated as
+      #
+      # +---------+---------+---------+---------+---------+
+      # |    X    | f(X,A)  | f(X,B)  | f(X,C)  |   ...   |
+      # +---------+---------+---------+---------+---------+
+      #
+      # where X is the Share Index of the share, and A, B, and C are arrays
+      # of M octets; A[0] is equal to the first octet of the secret, B[0] is
+      # equal to the second octet of the secret, and so on.
+      #
+      secret_bytes.each do |byte|
+        # Unpack random Byte String into Byte Array of 8 bit unsigned Integers
+        r = SecureRandom.random_bytes(threshold - 1).unpack('C*')
+
+        # Build each share one byte at a time for each byte of the secret.
+        shares.map! { |s| s << Util.f(s[0], [byte] + r) }
+      end
+
+      # 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.
+      shares.map! do |s|
+        binary = (header + s.pack('C*')).force_encoding('ASCII-8BIT')
+        # join with URL safe '~'
+        human = ['tss', 'v1', identifier, threshold, Base64.urlsafe_encode64(binary)].join('~')
+        format == 'binary' ? binary : human
+      end
+    end
+
+    private
+
+    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)
+      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)
+      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)
+      if secret_bytes.size >= 65_535
+        raise TSS::ArgumentError, 'invalid secret, combined padded secret and hash are too large'
+      end
+    end
+
+    def share_header(identifier, hash_alg, threshold, share_len)
+      SHARE_HEADER_STRUCT.encode(identifier: identifier,
+                                 hash_id: Hasher.code(hash_alg),
+                                 threshold: threshold,
+                                 share_len: share_len)
+    end
+  end
+end

data/lib/tss/tss.rb

@@ -0,0 +1,15 @@
+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'
+    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'
+    end
+    TSS::Combiner.new(args).combine
+  end
+end

data/lib/tss/types.rb

@@ -0,0 +1,4 @@
+# dry-types
+module Types
+  include Dry::Types.module
+end

data/lib/tss/util.rb

@@ -0,0 +1,266 @@
+# Common utility and math functions
+module TSS
+  module Util
+    # 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
+    # placeholder, and is not actually used in any computation.
+    EXP = [0x01, 0x03, 0x05, 0x0f, 0x11, 0x33, 0x55, 0xff,
+         0x1a, 0x2e, 0x72, 0x96, 0xa1, 0xf8, 0x13, 0x35,
+         0x5f, 0xe1, 0x38, 0x48, 0xd8, 0x73, 0x95, 0xa4,
+         0xf7, 0x02, 0x06, 0x0a, 0x1e, 0x22, 0x66, 0xaa,
+         0xe5, 0x34, 0x5c, 0xe4, 0x37, 0x59, 0xeb, 0x26,
+         0x6a, 0xbe, 0xd9, 0x70, 0x90, 0xab, 0xe6, 0x31,
+         0x53, 0xf5, 0x04, 0x0c, 0x14, 0x3c, 0x44, 0xcc,
+         0x4f, 0xd1, 0x68, 0xb8, 0xd3, 0x6e, 0xb2, 0xcd,
+         0x4c, 0xd4, 0x67, 0xa9, 0xe0, 0x3b, 0x4d, 0xd7,
+         0x62, 0xa6, 0xf1, 0x08, 0x18, 0x28, 0x78, 0x88,
+         0x83, 0x9e, 0xb9, 0xd0, 0x6b, 0xbd, 0xdc, 0x7f,
+         0x81, 0x98, 0xb3, 0xce, 0x49, 0xdb, 0x76, 0x9a,
+         0xb5, 0xc4, 0x57, 0xf9, 0x10, 0x30, 0x50, 0xf0,
+         0x0b, 0x1d, 0x27, 0x69, 0xbb, 0xd6, 0x61, 0xa3,
+         0xfe, 0x19, 0x2b, 0x7d, 0x87, 0x92, 0xad, 0xec,
+         0x2f, 0x71, 0x93, 0xae, 0xe9, 0x20, 0x60, 0xa0,
+         0xfb, 0x16, 0x3a, 0x4e, 0xd2, 0x6d, 0xb7, 0xc2,
+         0x5d, 0xe7, 0x32, 0x56, 0xfa, 0x15, 0x3f, 0x41,
+         0xc3, 0x5e, 0xe2, 0x3d, 0x47, 0xc9, 0x40, 0xc0,
+         0x5b, 0xed, 0x2c, 0x74, 0x9c, 0xbf, 0xda, 0x75,
+         0x9f, 0xba, 0xd5, 0x64, 0xac, 0xef, 0x2a, 0x7e,
+         0x82, 0x9d, 0xbc, 0xdf, 0x7a, 0x8e, 0x89, 0x80,
+         0x9b, 0xb6, 0xc1, 0x58, 0xe8, 0x23, 0x65, 0xaf,
+         0xea, 0x25, 0x6f, 0xb1, 0xc8, 0x43, 0xc5, 0x54,
+         0xfc, 0x1f, 0x21, 0x63, 0xa5, 0xf4, 0x07, 0x09,
+         0x1b, 0x2d, 0x77, 0x99, 0xb0, 0xcb, 0x46, 0xca,
+         0x45, 0xcf, 0x4a, 0xde, 0x79, 0x8b, 0x86, 0x91,
+         0xa8, 0xe3, 0x3e, 0x42, 0xc6, 0x51, 0xf3, 0x0e,
+         0x12, 0x36, 0x5a, 0xee, 0x29, 0x7b, 0x8d, 0x8c,
+         0x8f, 0x8a, 0x85, 0x94, 0xa7, 0xf2, 0x0d, 0x17,
+         0x39, 0x4b, 0xdd, 0x7c, 0x84, 0x97, 0xa2, 0xfd,
+         0x1c, 0x24, 0x6c, 0xb4, 0xc7, 0x52, 0xf6, 0x00].freeze
+
+    # The LOG table. The elements are to be read from top to
+    # bottom and left to right. For example, LOG[1] is 0, LOG[8] is 75,
+    # and so on. Note that the LOG[0] entry is present only as a
+    # placeholder, and is not actually used in any computation.
+    LOG = [0,     0,   25,    1,   50,    2,   26,  198,
+         75,  199,   27,  104,   51,  238,  223,    3,
+         100,   4,  224,   14,   52,  141,  129,  239,
+         76,  113,    8,  200,  248,  105,   28,  193,
+         125, 194,   29,  181,  249,  185,   39,  106,
+         77,  228,  166,  114,  154,  201,    9,  120,
+         101,  47,  138,    5,   33,   15,  225,   36,
+         18,  240,  130,   69,   53,  147,  218,  142,
+         150, 143,  219,  189,   54,  208,  206,  148,
+         19,   92,  210,  241,   64,   70,  131,   56,
+         102, 221,  253,   48,  191,    6,  139,   98,
+         179,  37,  226,  152,   34,  136,  145,   16,
+         126, 110,   72,  195,  163,  182,   30,   66,
+         58,  107,   40,   84,  250,  133,   61,  186,
+         43,  121,   10,   21,  155,  159,   94,  202,
+         78,  212,  172,  229,  243,  115,  167,   87,
+         175,  88,  168,   80,  244,  234,  214,  116,
+         79,  174,  233,  213,  231,  230,  173,  232,
+         44,  215,  117,  122,  235,   22,   11,  245,
+         89,  203,   95,  176,  156,  169,   81,  160,
+         127,  12,  246,  111,   23,  196,   73,  236,
+         216,  67,   31,   45,  164,  118,  123,  183,
+         204, 187,   62,   90,  251,   96,  177,  134,
+         59,   82,  161,  108,  170,   85,   41,  157,
+         151, 178,  135,  144,   97,  190,  220,  252,
+         188, 149,  207,  205,   55,   63,   91,  209,
+         83,   57,  132,   60,   65,  162,  109,   71,
+         20,   42,  158,   93,   86,  242,  211,  171,
+         68,   17,  146,  217,   35,   32,   46,  137,
+         180, 124,  184,   38,  119,  153,  227,  165,
+         103,  74,  237,  222,  197,   49,  254,   24,
+         13,   99,  140,  128,  192,  247,  112,    7].freeze
+
+    # The addition operation returns the Bitwise
+    # Exclusive OR (XOR) of its operands.
+    def self.gf256_add(a, b)
+      a ^ b
+    end
+
+    # The subtraction operation is identical, because the field has
+    # characteristic two.
+    def self.gf256_sub(a, b)
+      gf256_add(a, b)
+    end
+
+    # The multiplication operation takes two elements X and Y as input and
+    # 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.
+    def self.gf256_mul(x, y)
+      return 0 if x == 0 || y == 0
+      EXP[(LOG[x] + LOG[y]) % 255]
+    end
+
+    # The division operation takes a dividend X and a divisor Y as input
+    # and computes X divided by Y as follows.  If X is equal to 0x00, then
+    # 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.
+    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.
+    #
+    # 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
+    # defined as:
+    #
+    #   f(X, A) =  GF_SUM A[i] (*) X^i
+    #              i=0,M-1
+    #
+    # Because the GF_SUM summation takes place over GF(256), each addition
+    # uses the exclusive-or operation, and not integer addition.  Note that
+    # 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.
+    def self.f(x, bytes)
+      raise TSS::Error, 'invalid share index value, cannot be 0' if x == 0
+      y = 0
+      x_i = 1
+
+      bytes.each do |b|
+        y = gf256_add(y, gf256_mul(b, x_i))
+        x_i = gf256_mul(x_i, x)
+      end
+
+      y
+    end
+
+    # Secret Reconstruction Functions
+    # ###############################
+
+    # 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
+    #
+    #                             U[j]
+    #   L_i(U) = GF_PRODUCT   -------------
+    #            j=0,M-1, j!=i  U[j] (+) U[i]
+    #
+    # Here the product runs over all of the values of j from 0 to M-1,
+    # excluding the value i.  (This function is equal to ith Lagrange
+    # function, evaluated at zero.)  Note that the denominator in the above
+    # expression is never equal to zero because U[i] is not equal to U[j]
+    # whenever i is not equal to j.
+    #
+    def self.basis_poly(i, u)
+      prod = 1
+
+      (0..(u.length - 1)).each do |j|
+        next if i == j
+        prod = gf256_mul(prod, gf256_div(u[j], gf256_add(u[j], u[i])))
+      end
+
+      prod
+    end
+
+    # 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:
+    #
+    #   I(U, V) =  GF_SUM  L_i(U) (*) V[i].
+    #              i=0,M-1
+    #
+    def self.lagrange_interpolation(u, v)
+      sum = 0
+
+      (0..(v.length - 1)).each do |i|
+        sum = gf256_add(sum, gf256_mul(basis_poly(i, u), v[i]))
+      end
+
+      sum
+    end
+
+    # Conversion Functions
+    ######################
+
+    # String to Byte Array
+    def self.utf8_to_bytes(str)
+      str.bytes.to_a
+    end
+
+    # Byte Array to String
+    def self.bytes_to_utf8(bytes)
+      bytes.pack('C*').force_encoding('utf-8')
+    end
+
+    def self.bytes_to_hex(bytes)
+      hex = ''
+      bytes.each { |b| hex += sprintf('%02x', b).upcase }
+      hex
+    end
+
+    def self.hex_to_bytes(str)
+      # clone so we don't destroy the original string passed in by slicing it.
+      strc = str.clone
+      bytes = []
+      len = strc.length
+      raise TSS::Error, 'invalid hex value, cannot be an odd length' if len.odd?
+      # slice off two hex chars at a time and convert them to an Integer Byte.
+      (len / 2).times { bytes << strc.slice!(0, 2).hex }
+      bytes
+    end
+
+    def self.hex_to_utf8(hex)
+      bytes_to_utf8(hex_to_bytes(hex))
+    end
+
+    def self.utf8_to_hex(str)
+      bytes_to_hex(utf8_to_bytes(str))
+    end
+
+    # String Helpers
+
+    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)
+      return input_string if pad_length == byte_multiple
+      (pad_char * pad_length) + input_string
+    end
+
+    # Binary Header Helpers
+
+    def self.extract_share_header(share)
+      h = Splitter::SHARE_HEADER_STRUCT.decode(share)
+      h[:identifier] = h[:identifier].delete("\x00")
+      return h
+    end
+
+    # Math Helpers
+
+    def self.factorial(n)
+      (1..n).reduce(:*) || 1
+    end
+
+    # 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
+    #
+    # n is the total number of shares
+    # r is the threshold number of shares
+    def self.calc_combinations(n, r)
+      factorial(n) / (factorial(r) * factorial(n - r))
+    end
+
+    def self.int_commas(n, delimiter = ',')
+      n.to_s.reverse.gsub(%r{([0-9]{3}(?=([0-9])))}, "\\1#{delimiter}").reverse
+    end
+  end
+end