codex32 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e303c201093a87d6b4c458ccd892a8f217c0fdef841e6d3e94360e1f607b22e2
-  data.tar.gz: f2c8aa7553fb789a7e3b743cd8860a4e36c3e815574b8ac32dfa62fd7535f143
+  metadata.gz: 93df6005aec8470948875ab612155a1c3380bf79774b77f0d6d1a8059e9afa82
+  data.tar.gz: c4229ff6918b00717dcd3db5bf1a93f7464b9dabdd7ec7c6d9ebff71a6321d30
 SHA512:
-  metadata.gz: b42a64b0bc476c46d8c2bf40515d3ada761721cffc5332624384492e3755c64ba0e06480debc96cee011ee498b9531f51fd8f2bbc01b3c6955f88750939c754a
-  data.tar.gz: 9e1c7ad5976a72dc5dfcc043b979a71faf7f025b415d53030cd907591592c736a4e15a60f2f22f4ba962bbc8b01817c3916876071b4e5a9957a004d50f4b10d5
+  metadata.gz: 4dc15829c70fcc68c250063312c2d86d0deb30628286c2d72157dc07c44fab1beb2c124f116423bc3b99d79629f34171023e2e30eff7f80a29b7a66e310476df
+  data.tar.gz: 1661ba5642dc6c28394b7be554d59bcde96d6bc72103273adf5c04acce56d13234226a647912dbe5cb1d7826541c49f5d9c8ca12c3aa91e1b42b8dcd1b36a796

data/.rubocop.yml

@@ -4,20 +4,16 @@ require:
 inherit_gem:
   prettier: rubocop.yml
 AllCops:
-  TargetRubyVersion: 2.7
+  TargetRubyVersion: 3.0
 RSpec/ExampleLength:
   Enabled: false
 Metrics:
   Enabled: false
-RSpec/MultipleExpectations:
-  Max: 5
 Style/IfUnlessModifier:
   Enabled: false
 Style/WhileUntilModifier:
   Enabled: false
 Naming/MethodParameterName:
   Enabled: false
-RSpec/FilePath:
-  Enabled: false
 RSpec/MultipleExpectations:
   Enabled: false

data/.ruby-version

@@ -1 +1 @@
-ruby-3.2.0
+ruby-4.0.0

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 ## [Unreleased]
 
+### Added
+
+- `Codex32.split` splits a master seed into shares using `SecureRandom` and
+  verifies that the generated shares recover the seed. Creating shares from
+  anything but cryptographically secure randomness leaks the master seed, and
+  the library previously offered no way to do it.
+- A "Security considerations" section in the README, covering the lack of
+  constant time operations and of memory wiping.
+
+### Removed
+
+- `Codex32::Errors::SeparatorNotFound`. It was never raised: a string which
+  starts with `ms` but has no separator is reported as
+  `Codex32::Errors::InvalidHRP`, the same as the invalid test vectors of BIP-93
+  which mix a missing prefix and a missing separator.
+
+### Security
+
+- `Codex32.generate_share` no longer returns an all-zero share when the requested
+  share index collides with the index of one of the given shares. The check was
+  comparing a bech32 character with its integer value, so it never matched and
+  the Lagrange interpolation silently collapsed to zero. It now raises
+  `Codex32::Errors::DuplicateShareIndex`.
+- `Codex32.from` validates the master seed. A non hexadecimal, odd length or out
+  of range (128 to 512 bits) seed used to be silently converted into a different
+  value by `Array#pack`. It now raises `Codex32::Errors::InvalidSeed`.
+- `Codex32.parse` treats the last `1` as the separator, as BIP-93 requires.
+  Appending `1` and arbitrary data to a valid codex32 string is no longer
+  accepted, and the length is validated against the data part rather than the
+  whole string.
+
+### Fixed
+
+- `Codex32.generate_share` compares the number of shares with the threshold of
+  the shares themselves instead of the threshold of the first share, raises
+  `Codex32::Errors::PayloadLengthMismatch` for shares with different payload
+  lengths, and raises `Codex32::Errors::IdentifierMismatch` (previously a
+  `NameError` was raised because of a missing namespace).
+- `Codex32::Share#initialize` accepts an upper case `S` as the secret index.
+- `Codex32.convert_bits` raises `ArgumentError` for a value which does not fit
+  in the source bit width instead of returning `nil`, which the callers did not
+  check for.
+
 ## [0.1.0] - 2023-03-12
 
 - Initial release

data/Gemfile

@@ -9,7 +9,7 @@ gem "rake", "~> 13.0"
 
 gem "rspec", "~> 3.0"
 
-gem 'prettier'
+gem 'prettier', "4.0.3"
 
 gem 'rubocop-rake'
 gem 'rubocop-rspec'

data/README.md

@@ -29,6 +29,16 @@ share = Codex32.parse("ms10testsxxxxxxxxxxxxxxxxxxxxxxxxxx4nzvca9cmczlw")
 # Get share data.
 share.data
 
+# Split a master seed into 5 shares, any 3 of which recover the seed.
+# The shares are derived from random values obtained from SecureRandom.
+shares = Codex32.split(
+  seed: "ffeeddccbbaa99887766554433221100",
+  id: "test",
+  threshold: 3,
+  share_indexes: %w[a c d e f]
+)
+shares.map(&:to_s)
+
 # Recovery master seed using shares.
 share1 = Codex32.parse("MS12NAMEA320ZYXWVUTSRQPNMLKJHGFEDCAXRPP870HKKQRM")
 share2 = Codex32.parse("MS12NAMECACDEFGHJKLMNPQRSTUVWXYZ023FTR2GDZMPY6PN")
@@ -41,4 +51,23 @@ secret.data
 share3 = Codex32.generate_share([share1, share2], "d")
 # Obtain bech32 string.
 share3.to_s
-```
+```
+
+## Security considerations
+
+Codex32 strings and master seeds are secret material. Keep the following
+limitations in mind.
+
+- **Use `Codex32.split` to create shares.** Shares built from anything but
+  cryptographically secure randomness leak the master seed. `Codex32.split`
+  uses `SecureRandom`.
+- **Verify a backup before relying on it.** Recover the master seed from a
+  threshold of the shares and compare it with the original. `Codex32.split`
+  performs this check once for the shares it returns.
+- **This library is not constant time.** Character lookups, the field
+  arithmetic and the validation errors all depend on the data being processed.
+  Run it on a machine you trust, preferably offline, and do not feed it input
+  from untrusted parties on a shared host.
+- **Secrets are not erased from memory.** Ruby gives a library no reliable way
+  to wipe a string, so master seeds and shares stay in the heap until they are
+  garbage collected, and may be copied by the GC or swapped to disk.

data/codex32.gemspec

@@ -9,14 +9,14 @@ Gem::Specification.new do |spec|
   spec.email = ["techmedia.think@gmail.com"]
 
   spec.summary = "Ruby implementation of codex32"
-  spec.description = spec.description 
+  spec.description = spec.summary
   spec.homepage = "https://github.com/azuchi/codex32rb"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.7.0"
+  spec.required_ruby_version = ">= 3.0.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage 
-  spec.metadata["changelog_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/master/CHANGELOG.md"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

data/lib/codex32/errors.rb

@@ -22,9 +22,6 @@ module Codex32
     class InvalidHRP < Error
     end
 
-    class SeparatorNotFound < Error
-    end
-
     class InvalidIdentifier < Error
     end
 
@@ -45,5 +42,11 @@ module Codex32
 
     class InvalidCase < Error
     end
+
+    class InvalidSeed < Error
+    end
+
+    class PayloadLengthMismatch < Error
+    end
   end
 end

data/lib/codex32/share.rb

@@ -22,7 +22,7 @@ module Codex32
       @index = index.downcase
       @threshold = threshold
 
-      if threshold.zero? && index != SECRET_INDEX
+      if threshold.zero? && @index != SECRET_INDEX
         raise Codex32::Errors::InvalidShareIndex
       end
 

data/lib/codex32/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Codex32
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/codex32.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 require_relative "codex32/version"
 require_relative "codex32/errors"
 require_relative "codex32/share"
@@ -22,6 +24,16 @@ module Codex32
 
   SECRET_INDEX = "s"
 
+  # Minimum/maximum length of the data part (the part after the separator).
+  # 45 = threshold(1) + id(4) + index(1) + payload(26) + checksum(13)
+  # 124 = 127 (maximum length of a codex32 string) - "ms1"
+  MIN_DATA_LENGTH = 45
+  MAX_DATA_LENGTH = 124
+
+  # Minimum/maximum byte length of a master seed (128 bits to 512 bits).
+  MIN_SEED_LENGTH = 16
+  MAX_SEED_LENGTH = 64
+
   module_function
 
   # Parse codex32 string.
@@ -31,10 +43,14 @@ module Codex32
     if codex32.downcase != codex32 && codex32.upcase != codex32
       raise Errors::InvalidCase
     end
-    hrp, remain = codex32.downcase.split(SEPARATOR)
-    raise Errors::InvalidHRP unless hrp.downcase == HRP
-    raise Errors::InvalidLength if codex32.length < 48 || codex32.length > 127
-    raise Errors::SeparatorNotFound if remain.nil?
+    lower = codex32.downcase
+    # The separator is the *last* occurrence of SEPARATOR, everything before it is the HRP.
+    pos = lower.rindex(SEPARATOR)
+    raise Errors::InvalidHRP unless pos && lower[0...pos] == HRP
+    remain = lower[(pos + 1)..]
+    if remain.length < MIN_DATA_LENGTH || remain.length > MAX_DATA_LENGTH
+      raise Errors::InvalidLength
+    end
     unless valid_checksum?(bech32_to_array(remain))
       raise Errors::InvalidChecksum
     end
@@ -60,7 +76,13 @@ module Codex32
   def from(seed:, id:, share_index:, threshold: 0)
     raise Errors::InvalidThreshold unless threshold.is_a?(Integer)
     raise Errors::InvalidIdentifier unless id.length == 4
-    raise Errors::InvalidBech32Character if CHARSET.index(share_index).nil?
+    unless id.downcase.each_char.all? { |c| CHARSET.include?(c) }
+      raise Errors::InvalidBech32Character
+    end
+    if CHARSET.index(share_index.downcase).nil?
+      raise Errors::InvalidBech32Character
+    end
+    validate_seed!(seed)
     payload =
       array_to_bech32(
         convert_bits([seed].pack("H*").unpack("C*"), 8, 5, padding: true)
@@ -68,6 +90,87 @@ module Codex32
     Share.new(id, threshold, share_index, payload)
   end
 
+  # Split +seed+ into +share_indexes.length+ shares, any +threshold+ of which
+  # recover the seed. The shares are derived from random values obtained from
+  # +SecureRandom+.
+  # @param [String] seed Secret with hex format.
+  # @param [String] id Identifier.
+  # @param [Integer] threshold Threshold value. Must be 2 to 9.
+  # @param [Array(String)] share_indexes Indexes of the shares to be created.
+  # @return [Array(Codex32::Share)] Shares in the order of +share_indexes+.
+  def split(seed:, id:, threshold:, share_indexes:)
+    unless threshold.is_a?(Integer) && threshold > 1 && threshold < 10
+      raise Errors::InvalidThreshold
+    end
+    unless share_indexes.is_a?(Array)
+      raise ArgumentError, "share_indexes must be array."
+    end
+    indexes = share_indexes.map(&:downcase)
+    if indexes.any? { |i| CHARSET.index(i).nil? }
+      raise Errors::InvalidBech32Character
+    end
+    unless indexes.uniq.length == indexes.length
+      raise ArgumentError, "Share index duplicate."
+    end
+    raise Errors::InvalidShareIndex if indexes.include?(SECRET_INDEX)
+    raise Errors::InsufficientShares if indexes.length < threshold
+
+    secret =
+      from(seed: seed, id: id, share_index: SECRET_INDEX, threshold: threshold)
+    # Any +threshold+ shares define the polynomial, so the secret share and
+    # threshold - 1 random shares are enough to derive the remaining ones.
+    random_shares =
+      indexes
+        .take(threshold - 1)
+        .map do |i|
+          Share.new(id, threshold, i, random_payload(seed.length / 2))
+        end
+    known = [secret] + random_shares
+    shares =
+      indexes.map do |i|
+        random_shares.find { |s| s.index == i } || generate_share(known, i)
+      end
+    verify_shares!(shares.take(threshold), secret)
+    shares
+  end
+
+  # Generate a random payload which encodes +byte_length+ bytes.
+  # @param [Integer] byte_length Byte length of the payload.
+  # @return [String] bech32 string.
+  def random_payload(byte_length)
+    array_to_bech32(
+      convert_bits(
+        SecureRandom.random_bytes(byte_length).unpack("C*"),
+        8,
+        5,
+        padding: true
+      )
+    )
+  end
+
+  # Check that +shares+ actually recover +secret+.
+  # @param [Array(Codex32::Share)] shares Array of share.
+  # @param [Codex32::Share] secret Expected secret.
+  # @raise [Codex32::Errors::Error]
+  def verify_shares!(shares, secret)
+    return if generate_share(shares, SECRET_INDEX).to_s == secret.to_s
+    raise Errors::Error, "Failed to verify the generated shares."
+  end
+
+  # Validate that +seed+ is a hex string which encodes a master seed of
+  # 128 to 512 bits.
+  # @param [String] seed Secret with hex format.
+  # @raise [Codex32::Errors::InvalidSeed]
+  def validate_seed!(seed)
+    unless seed.is_a?(String) && seed.match?(/\A\h*\z/) && seed.length.even?
+      raise Errors::InvalidSeed, "seed must be an even-length hex string."
+    end
+    byte_length = seed.length / 2
+    return if byte_length.between?(MIN_SEED_LENGTH, MAX_SEED_LENGTH)
+    raise Errors::InvalidSeed,
+          "seed must be #{MIN_SEED_LENGTH} to #{MAX_SEED_LENGTH} bytes."
+  end
+
   # Convert bech32 string to array.
   # @param [String] bech32_str bech32 string.
   # @return [Array(Integer)] array of bech32 data.
@@ -85,7 +188,8 @@ module Codex32
   # @return [Codex32::Share] Recovery secret.
   def generate_share(shares, share_index)
     raise ArgumentError, "shares must be array." unless shares.is_a?(Array)
-    raise IdentifierMismatch unless shares.map(&:id).uniq.length == 1
+    raise ArgumentError, "shares must not be empty." if shares.empty?
+    raise Errors::IdentifierMismatch unless shares.map(&:id).uniq.length == 1
     threshold = shares.map(&:threshold).uniq
     threshold.delete(0)
     raise Errors::ThresholdMismatch unless threshold.length == 1
@@ -95,8 +199,15 @@ module Codex32
     unless indices.length == shares.length
       raise ArgumentError, "Share index duplicate."
     end
-    raise Errors::DuplicateShareIndex if indices.first == index
-    raise Errors::InsufficientShares if shares.length < shares[0].threshold
+    # The interpolation collapses to all zeros if +index+ collides with any
+    # existing share index, so every index must be checked, not just the first.
+    if indices.any? { |i| CHARSET.index(i) == index }
+      raise Errors::DuplicateShareIndex
+    end
+    raise Errors::InsufficientShares if shares.length < threshold.first
+    unless shares.map { |s| s.payload.length }.uniq.length == 1
+      raise Errors::PayloadLengthMismatch
+    end
 
     data =
       shares.map do |share|
@@ -171,7 +282,9 @@ module Codex32
     maxv = (1 << to) - 1
     max_acc = (1 << (from + to - 1)) - 1
     data.each do |v|
-      return nil if v.negative? || (v >> from) != 0
+      if v.negative? || (v >> from) != 0
+        raise ArgumentError, "#{v} does not fit in #{from} bits."
+      end
       acc = ((acc << from) | v) & max_acc
       bits += from
       while bits >= to

metadata

@@ -1,16 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: codex32
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - azuchi
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-03-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: ''
+description: Ruby implementation of codex32
 email:
 - techmedia.think@gmail.com
 executables: []
@@ -42,8 +41,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/azuchi/codex32rb
   source_code_uri: https://github.com/azuchi/codex32rb
-  changelog_uri: https://github.com/azuchi/codex32rb
-post_install_message: 
+  changelog_uri: https://github.com/azuchi/codex32rb/blob/master/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -51,15 +49,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
-signing_key: 
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Ruby implementation of codex32
 test_files: []