secretsharing 0.3 → 1.0.0

data/lib/secretsharing/shamir/container.rb

@@ -0,0 +1,93 @@
+# -*- encoding: utf-8 -*-
+
+# Copyright 2011-2015 Alexander Klink and Glenn Rempe
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module SecretSharing
+  module Shamir
+    # The SecretSharing::Shamir::Container class can be used to share random
+    # secrets between n people, so that k < n people can recover the
+    # secret, but k-1 people learn nothing (in an information-theoretical
+    # sense) about the secret.
+    #
+    # For a theoretical background, see:
+    #   http://www.cs.tau.ac.il/~bchor/Shamir.html
+    #   http://en.wikipedia.org/wiki/Secret_sharing#Shamir.27s_scheme
+    #
+    class Container
+      include SecretSharing::Shamir
+      attr_reader :n, :k, :secret, :shares
+
+      MIN_SHARES               = 2
+      MAX_SHARES               = 512
+
+      # To create a new SecretSharing::Shamir::Container object, you can
+      # pass either just n, or n and k where:
+      #
+      #   n = The total number of shares that will be created.
+      #   k = The threshold number of the total shares needed to
+      #       recreate the original secret. (Default = n)
+      #
+      # For example:
+      #
+      #   # 3(k) out of 5(n) shares needed to recover secret
+      #   s = SecretSharing::Shamir::Container.new(5, 3)
+      #
+      #   # 3(k) out of 3(n) shares needed to recover secret
+      #   s = SecretSharing::Shamir::Container.new(3)
+      #
+      def initialize(n, k = n)
+        @n               = n.to_i
+        @k               = k.to_i
+
+        fail ArgumentError, 'n must be an Integer' unless @n.is_a?(Integer)
+        fail ArgumentError, 'k must be an Integer' unless @k.is_a?(Integer)
+
+        fail ArgumentError, 'k must be <= n'              unless @k <= @n
+        fail ArgumentError, 'k must be >= #{MIN_SHARES}'  unless @k >= MIN_SHARES
+        fail ArgumentError, 'n must be <= #{MAX_SHARES}'  unless @n <= MAX_SHARES
+
+        @secret          = nil
+        @shares          = []
+      end
+
+      def secret?
+        @secret.is_a?(SecretSharing::Shamir::Secret)
+      end
+
+      def secret=(sec)
+        fail ArgumentError, 'secret has already been set' if secret?
+        fail ArgumentError, 'secret must be a SecretSharing::Shamir::Secret instance' unless sec.is_a?(SecretSharing::Shamir::Secret)
+        @secret = sec
+        @shares = Share.create_shares(@k, @n, @secret)
+        true
+      end
+
+      # Add a secret share to the object. Accepts a
+      # SecretSharing::Shamir::Share instance.
+      # Returns secret as a SecretSharing::Shamir::Secret if enough valid shares have been added
+      # to recover the secret, and false otherwise. The secret can also be recovered
+      # later with SecretSharing::Shamir::Container#secret if enough valid shares were previously
+      # provided.
+      def <<(share)
+        # You can't add more shares than were originally generated with value of @n
+        fail ArgumentError, 'You have added more shares than allowed by the value of @n' if @shares.size >= @n
+
+        share = SecretSharing::Shamir::Share.new(:share => share) unless share.is_a?(SecretSharing::Shamir::Share)
+        @shares << share unless @shares.include?(share)
+        @secret = Share.recover_secret(@shares)
+      end
+    end # class Container
+  end # module Shamir
+end # module SecretSharing

data/lib/secretsharing/shamir/secret.rb

@@ -0,0 +1,123 @@
+# -*- encoding: utf-8 -*-
+
+# Copyright 2011-2015 Glenn Rempe
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module SecretSharing
+  module Shamir
+    # A SecretSharing::Shamir::Secret object represents a Secret in the
+    # Shamir secret sharing scheme. Secrets can be passed in as an input
+    # argument when creating a new SecretSharing::Shamir::Container or
+    # can be the output from a Container that has successfully decoded shares.
+    # A new Secret take 0 or 1 args. Zero args means the Secret will be initialized
+    # with a random OpenSSL::BN object with the Secret::DEFAULT_BITLENGTH. If a
+    # single argument is passed it can be one of two object types, String or
+    # OpenSSL::BN.  If a String it is expected to be a specially encoded String
+    # that was generated as the output of calling #to_s on another Secret object.
+    # If the object type is OpenSSL::BN it can represent a number up to 4096 num_bits
+    # in length as reported by OpenSSL::BN#num_bits.
+    #
+    # All secrets are internally represented as an OpenSSL::BN which can be retrieved
+    # in its raw form using #secret.
+    #
+    class Secret
+      include SecretSharing::Shamir
+
+      # FIXME : Is a MAX_BITLENGTH really needed?  Can it be larger if so?
+
+      MAX_BITLENGTH = 4096
+
+      attr_accessor :secret, :bitlength, :hmac
+
+      # FIXME : allow instantiating a secret with any random number bitlength you choose.
+
+      def initialize(opts = {})
+        opts = {
+          :secret => get_random_number(256)
+        }.merge!(opts)
+
+        # override with options
+        opts.each_key do |k|
+          if self.respond_to?("#{k}=")
+            send("#{k}=", opts[k])
+          else
+            fail ArgumentError, "Argument '#{k}' is not allowed"
+          end
+        end
+
+        # FIXME : Do we really need the ability for a String arg to re-instantiate a Secret?
+        # FIXME : If its a String, shouldn't it be able to be an arbitrary String converted to/from OpenSSL::BN?
+
+        if opts[:secret].is_a?(String)
+          # Decode a Base64.urlsafe_encode64 String which contains a Base 36 encoded Bignum back into an OpenSSL::BN
+          # See : Secret#to_s for forward encoding method.
+          decoded_secret = usafe_decode64(opts[:secret])
+          fail ArgumentError, 'invalid base64 (returned nil or empty String)' if decoded_secret.empty?
+          @secret = OpenSSL::BN.new(decoded_secret.to_i(36).to_s)
+        end
+
+        @secret = opts[:secret] if @secret.nil?
+        fail ArgumentError, "Secret must be an OpenSSL::BN, not a '#{@secret.class}'" unless @secret.is_a?(OpenSSL::BN)
+        @bitlength = @secret.num_bits
+        fail ArgumentError, "Secret must have a bitlength less than or equal to #{MAX_BITLENGTH}" if @bitlength > MAX_BITLENGTH
+
+        generate_hmac
+      end
+
+      # Secrets are equal if the OpenSSL::BN in @secret is the same.
+      def ==(other)
+        other == @secret
+      end
+
+      # Set a new secret forces regeneration of the HMAC
+      def secret=(secret)
+        @secret = secret
+        generate_hmac
+      end
+
+      def secret?
+        @secret.is_a?(OpenSSL::BN)
+      end
+
+      def to_s
+        # Convert the OpenSSL::BN secret to an Bignum which has a #to_s(36) method
+        # Convert the Bignum to a Base 36 encoded String
+        # Wrap the Base 36 encoded String as a URL safe Base 64 encoded String
+        # Combined this should result in a relatively compact and portable String
+        usafe_encode64(@secret.to_i.to_s(36))
+      end
+
+      def valid_hmac?
+        return false if !@secret.is_a?(OpenSSL::BN) || @hmac.to_s.empty? || @secret.to_s.empty?
+
+        hmac_key  = @secret.to_s
+        hmac_data = OpenSSL::Digest::SHA256.new(@secret.to_s).hexdigest
+
+        @hmac == OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, hmac_key, hmac_data)
+      end
+
+      private
+
+      # The HMAC uses the raw secret itself as the HMAC key, and the SHA256 of the secret as the data.
+      # This allows later regeneration of the HMAC to confirm that the restored secret is in fact
+      # identical to what was originally split into shares.
+      def generate_hmac
+        return false if @secret.to_s.empty?
+        hmac_key  = @secret.to_s
+        hmac_data = OpenSSL::Digest::SHA256.new(@secret.to_s).hexdigest
+        @hmac     = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, hmac_key, hmac_data)
+      end
+    end # class Secret
+  end # module Shamir
+end # module SecretSharing

data/lib/secretsharing/shamir/share.rb

@@ -0,0 +1,156 @@
+# -*- encoding: utf-8 -*-
+
+# Copyright 2011-2015 Alexander Klink and Glenn Rempe
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module SecretSharing
+  module Shamir
+    # A SecretSharing::Shamir::Share object represents a share in the
+    # Shamir secret sharing scheme. The share consists of a point (x,y) on
+    # a polynomial over Z/Zp, where p is a prime.
+    class Share
+      include SecretSharing::Shamir
+      extend SecretSharing::Shamir
+      attr_accessor :share, :version, :hmac, :k, :n, :x, :y, :prime, :prime_bitlength
+
+      def initialize(opts = {})
+        opts = {
+          :share           => nil,
+          :version         => 1,
+          :hmac            => nil,
+          :k               => nil,
+          :n               => nil,
+          :x               => nil,
+          :y               => nil,
+          :prime           => nil,
+          :prime_bitlength => nil
+        }.merge!(opts)
+
+        opts.each_key do |k|
+          if self.respond_to?("#{k}=")
+            send("#{k}=", opts[k])
+          else
+            fail ArgumentError, "Argument '#{k}' is not allowed"
+          end
+        end
+
+        # Decode and unpack a String share if provided
+        unpack_share(@share) unless @share.nil?
+
+        if @share.nil?
+          errors = [:version, :hmac, :k, :n, :x, :y, :prime, :prime_bitlength].map { |e| e if send("#{e}").nil? }.compact
+          fail ArgumentError, "#{errors.join(', ')} expected." unless errors.empty?
+        end
+      end
+
+      def ==(other)
+        other.to_s == to_s
+      end
+
+      # FIXME : Add an HMAC which 'signs' all of the attributes of the hash and which gets verified on re-hydration to make sure
+      # that none of the attributes changed?
+
+      def to_hash
+        [:version, :hmac, :k, :n, :x, :y, :prime, :prime_bitlength].reduce({}) do |h, element|
+          if [:hmac].include?(element)
+            h.merge(element => send(element))
+          else
+            # everything else is an Integer/Bignum
+            h.merge(element => send(element).to_i)
+          end
+        end
+      end
+
+      def to_json
+        MultiJson.dump(to_hash)
+      end
+
+      def to_s
+        usafe_encode64(to_json)
+      end
+
+      # Creates the shares by computing random coefficients for a polynomial
+      # and then computing points on this polynomial.
+      def self.create_shares(k, n, secret)
+        shares                = []
+        coefficients          = []
+        coefficients[0]       = secret.secret
+
+        # round up to next nibble
+        next_nibble_bitlength = secret.bitlength + (4 - (secret.bitlength % 4))
+        prime_bitlength       = next_nibble_bitlength + 1
+        prime                 = OpenSSL::BN.generate_prime(prime_bitlength)
+
+        # FIXME : Why does generate_prime always return 35879 for bitlength 1-15
+        # OpenSSL::BN::generate_prime(1).to_i
+        # => 35879
+        # Do we need to make sure that prime_bitlength is not shorter than 64 bits?
+        # See : https://www.mail-archive.com/openssl-dev@openssl.org/msg18835.html
+        # See : http://ardoino.com/2005/11/maths-openssl-primes-random/
+        # See : http://www.openssl.org/docs/apps/genrsa.html  "Therefore the number of bits should not be less that 64."
+
+        # compute random coefficients
+        (1..k - 1).each { |x| coefficients[x] = get_random_number(secret.bitlength) }
+
+        (1..n).each do |x|
+          p_x = evaluate_polynomial_at(x, coefficients, prime)
+          new_share = new(:x => x, :y => p_x, :prime => prime, :prime_bitlength => prime_bitlength, :k => k, :n => n, :hmac => secret.hmac)
+          shares[x - 1] = new_share
+        end
+        shares
+      end
+
+      # Recover the secret by doing Lagrange interpolation.
+      def self.recover_secret(shares)
+        return false unless shares.length >= shares[0].k
+
+        # All Shares must have the same HMAC or they were derived from different Secrets
+        hmacs = shares.map(&:hmac).uniq
+        fail ArgumentError, 'Share mismatch. Not all Shares have a common HMAC.' unless hmacs.size == 1
+
+        secret = SecretSharing::Shamir::Secret.new(:secret => OpenSSL::BN.new('0'))
+
+        shares.each do |share|
+          l_x = lagrange(share.x, shares)
+          summand = share.y * l_x
+          summand %= share.prime
+          secret.secret += summand
+          secret.secret %= share.prime
+        end
+
+        if secret && secret.is_a?(SecretSharing::Shamir::Secret) && secret.valid_hmac?
+          return secret
+        else
+          fail ArgumentError, 'Secret recovery failure. The generated Secret does not match the HMACs in the Shares provided.'
+        end
+      end
+
+      private
+
+      def unpack_share(share)
+        decoded  = usafe_decode64(share)
+        h        = MultiJson.load(decoded, :symbolize_keys => true)
+
+        @version         = h[:version].to_i                unless h[:version].nil?
+        @hmac            = h[:hmac]                        unless h[:hmac].nil?
+        @k               = h[:k].to_i                      unless h[:k].nil?
+        @n               = h[:n].to_i                      unless h[:n].nil?
+        @x               = h[:x].to_i                      unless h[:x].nil?
+        @y               = OpenSSL::BN.new(h[:y].to_s)     unless h[:y].nil?
+        @prime           = OpenSSL::BN.new(h[:prime].to_s) unless h[:prime].nil?
+        @prime_bitlength = h[:prime_bitlength].to_i        unless h[:prime_bitlength].nil?
+      end
+    end # class Share
+  end # module Shamir
+end # module SecretSharing

data/lib/secretsharing/version.rb

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+
+# Copyright 2011-2015 Glenn Rempe
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Module for specifying the current version of the gem.
+module SecretSharing
+  VERSION = '1.0.0'
+end

data/secretsharing.gemspec

@@ -0,0 +1,47 @@
+# -*- encoding: utf-8 -*-
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'secretsharing/version'
+
+Gem::Specification.new do |s|
+  s.name              = "secretsharing"
+  s.version           = SecretSharing::VERSION
+  s.platform          = Gem::Platform::RUBY
+  s.authors           = ["Alexander Klink", "Glenn Rempe"]
+  s.email             = ["glenn@rempe.us"]
+  s.homepage          = "https://github.com/grempe/secretsharing"
+  s.summary           = %q{A Ruby Gem to enable sharing secrets using Shamirs Secret Sharing.}
+  s.license           = "APACHE 2.0"
+
+  s.has_rdoc          = 'true'
+  s.extra_rdoc_files  = ['README.md']
+
+  s.rubyforge_project = "secretsharing"
+
+  s.files             = `git ls-files`.split($/)
+  s.executables       = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files        = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths     = ["lib"]
+
+  s.add_dependency 'highline', '~> 1.6'
+  s.add_dependency 'multi_json', '~> 1.10'
+
+  s.add_development_dependency 'mocha'
+  s.add_development_dependency 'minitest'
+  s.add_development_dependency 'coco'
+  s.add_development_dependency 'rb-fsevent'
+  s.add_development_dependency 'rerun'
+  s.add_development_dependency 'rubocop'
+  s.add_development_dependency 'bundler', '~> 1.7'
+  s.add_development_dependency 'rake', '~> 10.4'
+
+  s.description =<<'XEOF'
+Shamir's Secret Sharing is an algorithm in cryptography. It is a
+form of secret sharing, where a secret is divided into parts,
+giving each participant its own unique part, where some of the
+parts or all of them are needed in order to reconstruct the
+secret. Holders of a share gain no knowledge of the larger secret.
+XEOF
+
+end

data/spec/shamir_container_spec.rb

@@ -0,0 +1,373 @@
+# -*- encoding: utf-8 -*-
+
+# Copyright 2011-2015 Glenn Rempe
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require File.expand_path('../spec_helper', __FILE__)
+
+describe SecretSharing::Shamir::Container do
+
+  describe 'initialization' do
+
+    it 'will raise when instantiated with no args' do
+      lambda { SecretSharing::Shamir::Container.new }.must_raise(ArgumentError)
+    end
+
+    it 'will create shares with n and k equal when given one Integer arg' do
+      s1 = SecretSharing::Shamir::Container.new(5)
+      s1.n.must_equal(5)
+      s1.k.must_equal(5)
+    end
+
+    it 'will create shares with n and k set to their own values when given two Integer args' do
+      s1 = SecretSharing::Shamir::Container.new(5, 3)
+      s1.n.must_equal(5)
+      s1.k.must_equal(3)
+    end
+
+    it 'will create shares with n and k equal when given one Integer as String arg' do
+      s1 = SecretSharing::Shamir::Container.new('5')
+      s1.n.must_equal(5)
+      s1.k.must_equal(5)
+    end
+
+    it 'will raise an exception with n being a non-Integer String arg' do
+      lambda { SecretSharing::Shamir::Container.new('foo') }.must_raise(ArgumentError)
+    end
+
+    it 'will create shares with n and k set to their own values when given two Integer as String args' do
+      s1 = SecretSharing::Shamir::Container.new('5', '3')
+      s1.n.must_equal(5)
+      s1.k.must_equal(3)
+    end
+
+    it 'will return false when secret? is called after initialization with only n arg set' do
+      s1 = SecretSharing::Shamir::Container.new(5)
+      s1.secret?.must_equal(false)
+    end
+
+    it 'will return false when secret? is called after initialization with n and k arg set' do
+      s1 = SecretSharing::Shamir::Container.new(5, 3)
+      s1.secret?.must_equal(false)
+    end
+
+    it 'will return nil secret when called after initialization with only n arg set' do
+      s1 = SecretSharing::Shamir::Container.new(5)
+      s1.secret.must_be_nil
+    end
+
+    it 'will return nil secret when called after initialization with n and k arg set' do
+      s1 = SecretSharing::Shamir::Container.new(5, 3)
+      s1.secret.must_be_nil
+    end
+
+    it 'will raise if k > n' do
+      lambda { SecretSharing::Shamir::Container.new(5, 6) }.must_raise(ArgumentError)
+    end
+
+    it 'will raise if only n is provided and it is < 2' do
+      lambda { SecretSharing::Shamir::Container.new(1) }.must_raise(ArgumentError)
+    end
+
+    it 'will raise unless k >= 2' do
+      lambda { SecretSharing::Shamir::Container.new(1, 1) }.must_raise(ArgumentError)
+    end
+
+    it 'will initialize if both k and n are at max size of 512' do
+      s1 = SecretSharing::Shamir::Container.new(512, 512)
+      s1.n.must_equal(512)
+      s1.k.must_equal(512)
+    end
+
+    it 'will raise if n > 512' do
+      lambda { SecretSharing::Shamir::Container.new(513) }.must_raise(ArgumentError)
+    end
+
+    it 'must return the correct min shares constant value' do
+      SecretSharing::Shamir::Container::MIN_SHARES.must_equal(2)
+    end
+
+    it 'must return the correct max shares constant value' do
+      SecretSharing::Shamir::Container::MAX_SHARES.must_equal(512)
+    end
+
+  end # describe initialization
+
+  describe 'creating a container and setting a secret' do
+
+    before do
+      @num_shares = 5
+      @c = SecretSharing::Shamir::Container.new(@num_shares)
+      @secret_num = OpenSSL::BN.new('1234567890')
+      @c.secret = SecretSharing::Shamir::Secret.new(:secret => @secret_num)
+    end
+
+    it 'will return true from #secret?' do
+      @c.secret?.must_equal(true)
+    end
+
+    it 'will not return a nil #secret' do
+      @c.secret.wont_be_nil
+    end
+
+    it 'will not return a nil #shares' do
+      @c.shares.wont_be_nil
+    end
+
+    it 'will return an Array of #shares' do
+      @c.shares.must_be_instance_of(Array)
+    end
+
+    it 'will return an Array of #shares of the same length as initialized with' do
+      @c.shares.size.must_equal(@num_shares)
+    end
+
+    it 'will return an Array of #shares each of the correct class' do
+      @c.shares.each do |share|
+        share.must_be_instance_of(SecretSharing::Shamir::Share)
+      end
+    end
+
+    it 'must raise an exception if a secret is attempted to be set more than once' do
+      lambda { @c.secret = SecretSharing::Shamir::Secret.new }.must_raise(ArgumentError)
+    end
+
+  end # creating a container and setting a secret
+
+  describe 'generating shares when a secret is provided' do
+
+    it 'should generate unique shares for the min number of shares and a tiny secret' do
+      c1 = SecretSharing::Shamir::Container.new(2)
+      c1.secret  = SecretSharing::Shamir::Secret.new(:secret => OpenSSL::BN.new('123'))
+      shares = c1.shares
+      shares.size.must_equal(2)
+      uniq_shares = shares.uniq
+      shares.must_equal(uniq_shares)
+    end
+
+    it 'should generate unique shares for the max number of shares and a tiny secret' do
+      c1 = SecretSharing::Shamir::Container.new(512)
+      c1.secret  = SecretSharing::Shamir::Secret.new(:secret => OpenSSL::BN.new('123'))
+      shares = c1.shares
+      shares.size.must_equal(512)
+      uniq_shares = shares.uniq
+      shares.must_equal(uniq_shares)
+    end
+
+    it 'should generate unique shares for the min number of shares and a large secret' do
+      c1 = SecretSharing::Shamir::Container.new(2)
+# FIXME : Major Perf Issue : If OpenSSL::BN::rand(512) is given with 4096 instead of 512 this takes FOREVER
+      c1.secret  = SecretSharing::Shamir::Secret.new(:secret => OpenSSL::BN::rand(512))
+      shares = c1.shares
+      shares.size.must_equal(2)
+      uniq_shares = shares.uniq
+      shares.must_equal(uniq_shares)
+    end
+
+    it 'should generate unique shares for the max number of shares and a large secret' do
+      c1 = SecretSharing::Shamir::Container.new(512)
+# FIXME : Major Perf Issue : If OpenSSL::BN::rand(512) is given with 4096 instead of 512 this takes FOREVER
+      c1.secret  = SecretSharing::Shamir::Secret.new(:secret => OpenSSL::BN::rand(512))
+      shares = c1.shares
+      shares.size.must_equal(512)
+      uniq_shares = shares.uniq
+      shares.must_equal(uniq_shares)
+    end
+
+  end
+
+  describe 'recovering a secret from a container' do
+
+    before do
+      @c1 = SecretSharing::Shamir::Container.new(5)    # creator
+      @c2 = SecretSharing::Shamir::Container.new(5)    # recipient
+
+      @c3 = SecretSharing::Shamir::Container.new(5, 3) # creator
+      @c4 = SecretSharing::Shamir::Container.new(5, 3) # recipient
+
+      @bad = SecretSharing::Shamir::Container.new(5, 3) # a bad actor
+    end
+
+    describe 'with a mix of valid and invalid shares' do
+
+      before do
+        # set a secret on the 'creators'
+        @c1.secret  = SecretSharing::Shamir::Secret.new
+        @c3.secret  = SecretSharing::Shamir::Secret.new
+        @bad.secret = SecretSharing::Shamir::Secret.new
+      end
+
+      it 'should be able to recover secret when k equals n and all k valid shares are provided as Shamir::Share objects' do
+        @c2 << @c1.shares[0]
+        @c2 << @c1.shares[1]
+        @c2 << @c1.shares[2]
+        @c2 << @c1.shares[3]
+
+        # with the last remaining share missing
+        @c2.secret?.must_equal(false)
+
+        @c2 << @c1.shares[4]
+
+        # with the final share provided
+        @c2.secret?.must_equal(true)
+        @c2.secret.must_equal(@c1.secret)
+      end
+
+      it 'should raise an ArgumentError if n + 1 shares are provided (more than were originally generated)' do
+        @c2 << @c1.shares[0]
+        @c2 << @c1.shares[1]
+        @c2 << @c1.shares[2]
+        @c2 << @c1.shares[3]
+        @c2.secret?.must_equal(false)
+        @c2 << @c1.shares[4]
+        @c2.secret?.must_equal(true)
+
+        lambda { @c2 << @bad.shares[0] }.must_raise(ArgumentError)
+      end
+
+      it 'should raise an ArgumentError when k equals n and k-1 valid shares and 1 invalid share are provided as Shamir::Share objects' do
+        @c2 << @c1.shares[0]
+        @c2 << @c1.shares[1]
+        @c2 << @c1.shares[2]
+        @c2 << @c1.shares[3]
+
+        # with the last remaining share missing
+        @c2.secret?.must_equal(false)
+
+        # with a bad share
+        lambda { @c2 << @bad.shares[0] }.must_raise(ArgumentError)
+      end
+
+      it 'should raise an ArgumentError if the final @secret generated does not have a valid_hmac?' do
+        # mocha instance mock using handy 'any_instance'
+        SecretSharing::Shamir::Secret.any_instance.stubs(:valid_hmac?).returns(false)
+        @c2 << @c1.shares[0]
+        @c2 << @c1.shares[1]
+        @c2 << @c1.shares[2]
+        @c2 << @c1.shares[3]
+        lambda { @c2 << @c1.shares[4] }.must_raise(ArgumentError)
+      end
+
+    end
+
+    describe 'with valid shares resulting from a random secret' do
+
+      before do
+        extend SecretSharing::Shamir
+        # set a secret on both of the 'creators'
+        @c1.secret = SecretSharing::Shamir::Secret.new
+        @c3.secret = SecretSharing::Shamir::Secret.new
+      end
+
+      # This exposed a bug in the prime number generation; for instance 4*8
+      # passes.
+      it 'should be able to recover secret with a bitlength of 5*8' do
+        secret = SecretSharing::Shamir::Secret.new(:secret => get_random_number(5*8))
+        c = SecretSharing::Shamir::Container.new(4,2)
+        c.secret = secret
+
+        (0...4).to_a.permutation(2).collect{|e| e.sort}.uniq.each do |indexes|
+          c2 = SecretSharing::Shamir::Container.new(2)
+          indexes.each do |index|
+            c2 << c.shares[index]
+          end
+          c2.secret?.must_equal(true)
+          c2.secret.must_equal(c.secret)
+        end
+      end
+
+      it 'should be able to recover secret when k equals n and all k shares are provided as Shamir::Share objects' do
+        @c2 << @c1.shares[0]
+        @c2 << @c1.shares[1]
+        @c2 << @c1.shares[2]
+        @c2 << @c1.shares[3]
+
+        # with the last remaining share missing
+        @c2.secret?.must_equal(false)
+
+        @c2 << @c1.shares[4]
+
+        # with the final share provided
+        @c2.secret?.must_equal(true)
+        @c2.secret.must_equal(@c1.secret)
+      end
+
+      it 'should be able to recover secret when k equals n and all k shares are provided as Shamir::Share objects converted to Strings' do
+        @c2 << @c1.shares[0].to_s
+        @c2 << @c1.shares[1].to_s
+        @c2 << @c1.shares[2].to_s
+        @c2 << @c1.shares[3].to_s
+
+        # with the last remaining share missing
+        @c2.secret?.must_equal(false)
+
+        @c2 << @c1.shares[4].to_s
+
+        # with the final share provided
+        @c2.secret?.must_equal(true)
+        @c2.secret.must_equal(@c1.secret)
+      end
+
+      it 'should be able to recover secret when k < n and minimum k shares are provided as Shamir::Share objects' do
+        @c4 << @c3.shares[0]
+        @c4 << @c3.shares[1]
+
+        # with the last remaining share missing
+        @c4.secret?.must_equal(false)
+
+        @c4 << @c3.shares[2]
+
+        # with the final share provided
+        @c4.secret?.must_equal(true)
+        @c4.secret.must_equal(@c3.secret)
+      end
+
+      it 'should be able to recover secret when k < n and minimum k shares are provided as Shamir::Share objects converted to Strings' do
+        @c4 << @c3.shares[0].to_s
+        @c4 << @c3.shares[1].to_s
+
+        # with the last remaining share missing
+        @c4.secret?.must_equal(false)
+
+        @c4 << @c3.shares[2].to_s
+
+        # with the final share provided
+        @c4.secret?.must_equal(true)
+        @c4.secret.must_equal(@c3.secret)
+      end
+
+      it 'should be able to recover secret when k < n and more than minimum k shares are provided as Shamir::Share objects converted to Strings' do
+        @c4 << @c3.shares[0].to_s
+        @c4 << @c3.shares[1].to_s
+
+        # with the last remaining share missing
+        @c4.secret?.must_equal(false)
+
+        @c4 << @c3.shares[2].to_s
+
+        # with the final needed share provided
+        @c4.secret?.must_equal(true)
+        @c4.secret.must_equal(@c3.secret)
+
+        # with an extra valid share provided
+        @c4 << @c3.shares[3].to_s
+        @c4.secret?.must_equal(true)
+        @c4.secret.must_equal(@c3.secret)
+      end
+
+    end
+
+  end # recovering a secret from a container
+
+end # describe SecretSharing::Shamir::Container