skeleton_key 0.1.0

data/lib/skeleton_key/recovery/slip39_support/generator.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "openssl"
+
+module SkeletonKey
+  module Recovery
+    module Slip39Support
+      ##
+      # Generates SLIP-0039 share mnemonics from a master secret.
+      class Generator
+        include Protocol
+
+        def initialize(wordlist:, customization_string:, cipher:, random_bytes: SecureRandom.method(:random_bytes))
+          @wordlist = wordlist
+          @customization_string = customization_string
+          @cipher = cipher
+          @random_bytes = random_bytes
+          @encoder = Encoder.new(wordlist: wordlist, customization_string: customization_string)
+        end
+
+        def generate(master_secret:, group_threshold:, groups:, passphrase:, extendable:, iteration_exponent:)
+          validate_passphrase!(passphrase)
+          validate_master_secret!(master_secret)
+          validate_groups!(group_threshold, groups)
+
+          identifier = random_identifier
+          ciphertext = @cipher.encrypt(master_secret, passphrase.b, iteration_exponent, identifier, extendable)
+          group_shares = split_secret(group_threshold, groups.length, ciphertext)
+
+          structured_groups = groups.map.with_index do |group_config, group_index|
+            member_threshold = group_config.fetch(:member_threshold)
+            member_count = group_config.fetch(:member_count)
+            member_shares = split_secret(member_threshold, member_count, group_shares.fetch(group_index).data)
+
+            share_objects = member_shares.map.with_index do |share, member_index|
+              Share.new(
+                identifier: identifier,
+                extendable: extendable,
+                iteration_exponent: iteration_exponent,
+                group_index: group_index,
+                group_threshold: group_threshold,
+                group_count: groups.length,
+                index: member_index,
+                member_threshold: member_threshold,
+                value: share.data
+              )
+            end
+
+            {
+              member_threshold: member_threshold,
+              member_count: member_count,
+              shares: share_objects.map { |share| @encoder.mnemonic_for_share(share) }
+            }
+          end
+
+          GeneratedSet.new(
+            identifier: identifier,
+            extendable: extendable,
+            iteration_exponent: iteration_exponent,
+            group_threshold: group_threshold,
+            groups: groups,
+            mnemonic_groups: structured_groups.map { |group| group.fetch(:shares) }
+          )
+        end
+
+        private
+
+        def validate_passphrase!(passphrase)
+          return if passphrase.bytes.all? { |byte| byte.between?(32, 126) }
+
+          raise Errors::InvalidSlip39ConfigurationError,
+                "SLIP-0039 passphrase must contain only printable ASCII characters"
+        end
+
+        def validate_master_secret!(master_secret)
+          unless Constants::SLIP39_SECRET_LENGTHS.include?(master_secret.bytesize)
+            raise Errors::InvalidSlip39ConfigurationError,
+                  "SLIP-0039 master secret must be #{Constants::SLIP39_SECRET_LENGTHS.inspect} bytes"
+          end
+        end
+
+        def validate_groups!(group_threshold, groups)
+          raise Errors::InvalidSlip39ConfigurationError, "SLIP-0039 groups must not be empty" if groups.empty?
+          raise Errors::InvalidSlip39ConfigurationError, "SLIP-0039 group threshold must be positive" if group_threshold < 1
+          if group_threshold > groups.length
+            raise Errors::InvalidSlip39ConfigurationError,
+                  "SLIP-0039 group threshold must not exceed the number of groups"
+          end
+
+          groups.each do |group|
+            member_threshold = group.fetch(:member_threshold)
+            member_count = group.fetch(:member_count)
+
+            if member_threshold < 1
+              raise Errors::InvalidSlip39ConfigurationError,
+                    "SLIP-0039 member threshold must be positive"
+            end
+
+            if member_threshold > member_count
+              raise Errors::InvalidSlip39ConfigurationError,
+                    "SLIP-0039 member threshold must not exceed member count"
+            end
+
+            if member_count > MAX_SHARE_COUNT
+              raise Errors::InvalidSlip39ConfigurationError,
+                    "SLIP-0039 member count must not exceed #{MAX_SHARE_COUNT}"
+            end
+
+            if member_threshold == 1 && member_count > 1
+              raise Errors::InvalidSlip39ConfigurationError,
+                    "SLIP-0039 does not allow member threshold 1 with multiple shares"
+            end
+          end
+        end
+
+        def random_identifier
+          identifier_bytes = @random_bytes.call(BitPacking.bits_to_bytes(ID_LENGTH_BITS))
+          identifier_bytes.unpack1("H*").to_i(16) & ((1 << ID_LENGTH_BITS) - 1)
+        end
+
+        def split_secret(threshold, share_count, shared_secret)
+          raise Errors::InvalidSlip39ConfigurationError, "SLIP-0039 threshold must be positive" if threshold < 1
+          if threshold > share_count
+            raise Errors::InvalidSlip39ConfigurationError,
+                  "SLIP-0039 threshold must not exceed share count"
+          end
+          if share_count > MAX_SHARE_COUNT
+            raise Errors::InvalidSlip39ConfigurationError,
+                  "SLIP-0039 share count must not exceed #{MAX_SHARE_COUNT}"
+          end
+
+          return (0...share_count).map { |index| RawShare.new(x: index, data: shared_secret) } if threshold == 1
+
+          random_share_count = threshold - 2
+          shares = (0...random_share_count).map do |index|
+            RawShare.new(x: index, data: @random_bytes.call(shared_secret.bytesize))
+          end
+
+          random_part = @random_bytes.call(shared_secret.bytesize - DIGEST_LENGTH_BYTES)
+          digest = OpenSSL::HMAC.digest("SHA256", random_part, shared_secret).byteslice(0, DIGEST_LENGTH_BYTES)
+          base_shares = shares + [
+            RawShare.new(x: DIGEST_INDEX, data: digest + random_part),
+            RawShare.new(x: SECRET_INDEX, data: shared_secret)
+          ]
+
+          (random_share_count...share_count).each do |index|
+            shares << RawShare.new(x: index, data: Interpolation.interpolate(base_shares, index))
+          end
+
+          shares
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/recovery/slip39_support/interpolation.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Recovery
+    module Slip39Support
+      ##
+      # GF(256) interpolation used to reconstruct SLIP-0039 secrets.
+      module Interpolation
+        module_function
+
+        def exp_table
+          @exp_table ||= begin
+            exp = Array.new(255, 0)
+            log = Array.new(256, 0)
+            poly = 1
+
+            255.times do |i|
+              exp[i] = poly
+              log[poly] = i
+              poly = (poly << 1) ^ poly
+              poly ^= 0x11B if (poly & 0x100) != 0
+            end
+
+            @log_table = log.freeze
+            exp.freeze
+          end
+        end
+
+        def log_table
+          exp_table
+          @log_table
+        end
+
+        def interpolate(shares, x_coordinate)
+          x_values = shares.map(&:x)
+          raise Errors::InvalidSlip39ShareError, "SLIP-0039 share indices must be unique" unless x_values.uniq.length == x_values.length
+
+          share_lengths = shares.map { |share| share.data.bytesize }.uniq
+          raise Errors::InvalidSlip39ShareError, "all SLIP-0039 share values must have the same length" unless share_lengths.length == 1
+
+          if (direct_hit = shares.find { |share| share.x == x_coordinate })
+            return direct_hit.data
+          end
+
+          log_prod = shares.sum { |share| log_table[share.x ^ x_coordinate] }
+          result = "\x00".b * share_lengths.first
+
+          shares.each do |share|
+            log_basis_eval = (
+              log_prod -
+              log_table[share.x ^ x_coordinate] -
+              shares.sum { |other| other == share ? 0 : log_table[share.x ^ other.x] }
+            ) % 255
+
+            result = result.bytes.zip(share.data.bytes).map do |intermediate, share_byte|
+              term =
+                if share_byte.zero?
+                  0
+                else
+                  exp_table[(log_table[share_byte] + log_basis_eval) % 255]
+                end
+              intermediate ^ term
+            end.pack("C*")
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/recovery/slip39_support/protocol.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Recovery
+    module Slip39Support
+      ##
+      # Protocol constants shared by the SLIP-0039 recovery helpers.
+      #
+      # These values are scoped to the SLIP-0039 implementation and should not
+      # leak into unrelated recovery or derivation code.
+      module Protocol
+        RADIX_BITS = 10
+        RADIX = 1 << RADIX_BITS
+        ID_LENGTH_BITS = 15
+        EXTENDABLE_FLAG_LENGTH_BITS = 1
+        ITERATION_EXP_LENGTH_BITS = 4
+        ID_EXP_LENGTH_WORDS = ((ID_LENGTH_BITS + EXTENDABLE_FLAG_LENGTH_BITS + ITERATION_EXP_LENGTH_BITS) + RADIX_BITS - 1) / RADIX_BITS
+        CHECKSUM_LENGTH_WORDS = 3
+        DIGEST_LENGTH_BYTES = 4
+        CUSTOMIZATION_STRING_ORIG = "shamir".b
+        CUSTOMIZATION_STRING_EXTENDABLE = "shamir_extendable".b
+        GROUP_PREFIX_LENGTH_WORDS = ID_EXP_LENGTH_WORDS + 1
+        METADATA_LENGTH_WORDS = ID_EXP_LENGTH_WORDS + 2 + CHECKSUM_LENGTH_WORDS
+        MIN_STRENGTH_BITS = 128
+        MIN_MNEMONIC_LENGTH_WORDS = METADATA_LENGTH_WORDS + ((MIN_STRENGTH_BITS + RADIX_BITS - 1) / RADIX_BITS)
+        BASE_ITERATION_COUNT = 10_000
+        ROUND_COUNT = 4
+        SECRET_INDEX = 255
+        DIGEST_INDEX = 254
+        MAX_SHARE_COUNT = 16
+      end
+    end
+  end
+end

data/lib/skeleton_key/recovery/slip39_support/secret_recovery.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module SkeletonKey
+  module Recovery
+    module Slip39Support
+      ##
+      # Reconstructs SLIP-0039 group fragments and encrypted master secrets.
+      class SecretRecovery
+        include Protocol
+
+        def recover_encrypted_master_secret(groups)
+          raise Errors::InvalidSlip39ShareError, "the set of SLIP-0039 shares is empty" if groups.empty?
+
+          params = groups.values.first.first
+          if groups.length < params.group_threshold
+            raise Errors::InvalidSlip39ShareError,
+                  "insufficient number of mnemonic groups: requires #{params.group_threshold}"
+          end
+
+          if groups.length != params.group_threshold
+            raise Errors::InvalidSlip39ShareError,
+                  "wrong number of mnemonic groups: expected #{params.group_threshold}, got #{groups.length}"
+          end
+
+          group_shares = groups.map do |group_index, shares|
+            if shares.length != shares.first.member_threshold
+              raise Errors::InvalidSlip39ShareError,
+                    "wrong number of mnemonics for group #{group_index}: expected #{shares.first.member_threshold}, got #{shares.length}"
+            end
+
+            RawShare.new(
+              x: group_index,
+              data: recover_secret(
+                shares.first.member_threshold,
+                shares.map { |share| RawShare.new(x: share.index, data: share.value) }
+              )
+            )
+          end
+
+          ciphertext = recover_secret(params.group_threshold, group_shares)
+          {
+            identifier: params.identifier,
+            extendable: params.extendable,
+            iteration_exponent: params.iteration_exponent,
+            ciphertext: ciphertext
+          }
+        end
+
+        private
+
+        def recover_secret(threshold, shares)
+          return shares.first.data if threshold == 1
+
+          shared_secret = Interpolation.interpolate(shares, SECRET_INDEX)
+          digest_share = Interpolation.interpolate(shares, DIGEST_INDEX)
+          digest = digest_share.byteslice(0, DIGEST_LENGTH_BYTES)
+          random_part = digest_share.byteslice(DIGEST_LENGTH_BYTES, digest_share.bytesize - DIGEST_LENGTH_BYTES)
+
+          unless digest == create_digest(random_part, shared_secret)
+            raise Errors::InvalidSlip39ShareError, "invalid digest of the shared secret"
+          end
+
+          shared_secret
+        end
+
+        def create_digest(random_data, shared_secret)
+          OpenSSL::HMAC.digest("SHA256", random_data, shared_secret).byteslice(0, DIGEST_LENGTH_BYTES)
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/recovery/slip39_support/share.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Recovery
+    module Slip39Support
+      # Minimal `(x, data)` tuple used during interpolation.
+      RawShare = Struct.new(:x, :data, keyword_init: true)
+
+      ##
+      # Parsed SLIP-0039 share metadata and value payload.
+      #
+      # Each share is self-describing. Recovery groups are reconstructed from
+      # these fields rather than from caller-supplied nested input.
+      Share = Struct.new(
+        :identifier,
+        :extendable,
+        :iteration_exponent,
+        :group_index,
+        :group_threshold,
+        :group_count,
+        :index,
+        :member_threshold,
+        :value,
+        keyword_init: true
+      ) do
+        # Parameters that must match across every share in a recovery set.
+        #
+        # @return [Array<Integer, Boolean>]
+        def common_parameters
+          [identifier, extendable, iteration_exponent, group_threshold, group_count]
+        end
+
+        # Parameters that must match within a single mnemonic group.
+        #
+        # @return [Array<Integer, Boolean>]
+        def group_parameters
+          [
+            identifier,
+            extendable,
+            iteration_exponent,
+            group_index,
+            group_threshold,
+            group_count,
+            member_threshold
+          ]
+        end
+      end
+    end
+  end
+end