derivator 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6fb64625fb015d83f804ddd0323ebc07825ea569dd1a1f2c739d7e8e143b7e65
+  data.tar.gz: 5f3519ad198b4ca049be879525df4e0d987a37f4a56b4969871188b007b132c3
+SHA512:
+  metadata.gz: e3e67c14744d3c3173178f17c6a6003694abc095b3a10a78a40c42f16f78fd1e8d25e937df05ebd793b4d4d6bd01013a5e923ad3508e23e0eae5106e7e25507e
+  data.tar.gz: 1abba063b0c1dfbbeb38e7f0db23d87da0179d021f25e0003dee1df0ffd9255504fbdfef34245eb4b9809d83cd8c9591b6f71ea0030a2ae38d158a22baeef011

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in derivator.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+
+gem 'rspec', '~> 3.0'

data/Gemfile.lock

@@ -0,0 +1,41 @@
+PATH
+  remote: .
+  specs:
+    derivator (0.1)
+      openssl (>= 3.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.5.0)
+    openssl (3.0.0)
+    rake (13.0.6)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-support (3.11.0)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  derivator!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  yard
+
+BUNDLED WITH
+   2.2.22

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 WAGMI LTD.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,115 @@
+# Derivator
+
+Ruby implementation of EC HD key derivation ([SLIP10](https://github.com/satoshilabs/slips/blob/master/slip-0010.md), [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)) and mnemonic sentence interpretation ([BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)).
+
+Supports secp256k1 (Bitcoin), nist256p1 (P-256) and ed25519 (Edwards 25519) elliptic curves.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'derivator'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install derivator
+
+## Usage
+
+### Generate mnemonic
+
+```bash
+# bash
+derivator_mnemonic
+```
+
+```ruby
+# ruby
+require 'derivator'
+
+puts Derivator::Mnemonic.generate
+```
+
+### Generate seed from mnemonic
+
+```bash
+# bash
+echo "finish merry file canoe cruel meadow spoil sunset pigeon depend brush step" | \
+  derivator_seed_from_mnemonic
+
+echo "spike kit woman maze culture uncle way tobacco saddle silly sunset certain" | \
+  derivator_seed_from_mnemonic "my_mnemonic_password"
+```
+
+```ruby
+# ruby
+require 'derivator'
+
+mnemonic = 'finish merry file canoe cruel meadow spoil sunset pigeon depend brush step'
+puts Derivator::Mnemonic.seed(mnemonic)
+
+mnemonic = 'spike kit woman maze culture uncle way tobacco saddle silly sunset certain'
+puts Derivator::Mnemonic.seed(mnemonic, 'my_mnemonic_password')
+```
+
+### Generate master key and chain code from seed
+
+```bash
+# bash
+echo 000102030405060708090a0b0c0d0e0f | derivator_key_from_seed ed25519
+```
+
+```ruby
+# ruby
+require 'derivator'
+
+seed = '000102030405060708090a0b0c0d0e0f'
+key = Derivator::Key.from_seed(seed, :ed25519)
+puts "#{key.private_key_hex} #{key.chain_code_hex}"
+```
+
+### Derive child key from master key and chain code
+
+```bash
+# bash
+echo 2b4be7f19ee27bbf30c667b642d5f4aa69fd169872f8fc3059c08ebae2eb19e7 90046a93de5380a72b5e45010748567d5ea02bbf6522f979e05c0d8d8ca9fffb \
+  derivator_key_from_parent "m/0'/1'/2'/2'/1000000000'" ed25519
+```
+
+```ruby
+# ruby
+require 'derivator'
+
+master_private_key_hex = '2b4be7f19ee27bbf30c667b642d5f4aa69fd169872f8fc3059c08ebae2eb19e7'
+master_chain_code_hex = '90046a93de5380a72b5e45010748567d5ea02bbf6522f979e05c0d8d8ca9fffb'
+key = Derivator::Key.from_hex(master_private_key_hex, master_chain_code_hex, :ed25519)
+derived_key = key.derive("m/0'/1'/2'/2'/1000000000'")
+puts "#{derived_key.private_key_hex} #{derived_key.chain_code_hex}"
+```
+
+### Derive public key from private key
+
+```bash
+# bash
+echo 2b4be7f19ee27bbf30c667b642d5f4aa69fd169872f8fc3059c08ebae2eb19e7 | \
+  derivator_public_from_private ed25519
+```
+
+```ruby
+# ruby
+require 'derivator'
+
+private_key_hex = '2b4be7f19ee27bbf30c667b642d5f4aa69fd169872f8fc3059c08ebae2eb19e7'
+key = Derivator::Key.from_hex(private_key_hex, '', :ed25519)
+puts key.public_key_hex
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'derivator'
+require 'derivator/refinements'
+
+include Derivator
+
+using Refinements
+
+require 'irb'
+IRB.start(__FILE__)

data/derivator.gemspec

@@ -0,0 +1,27 @@
+Gem::Specification.new do |spec|
+  spec.name          = 'derivator'
+  spec.version       = '0.1'
+  spec.authors       = ['WAGMI LTD.']
+  spec.email         = ['debifi@debifi.com']
+
+  spec.summary       = 'BIP-0039, BIP-0032, SLIP-0010 elliptic curve (P-256, ED25519, SECP256K1) keys derivator'
+  spec.homepage      = 'https://gitlab.com/debifi-public/derivator'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 2.4.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+
+  # 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.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'yard'
+
+  spec.add_dependency 'openssl', '>= 3.0'
+end

data/exe/derivator_key_from_parent

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+git_path = File.expand_path("../.git", __dir__)
+
+if File.exist?(git_path)
+  lib_path = File.expand_path("../lib", __dir__)
+  $:.unshift(lib_path)
+end
+
+require 'derivator'
+
+path = ARGV.first
+curve = ARGV[1] || 'secp256k1'
+private_key_hex, chain_code_hex = STDIN.gets.split
+key = Derivator::Key.from_hex(private_key_hex, chain_code_hex, curve.to_sym)
+derived_key = key.derive(path)
+puts "#{derived_key.private_key_hex} #{derived_key.chain_code_hex}"

data/exe/derivator_key_from_seed

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+git_path = File.expand_path("../.git", __dir__)
+
+if File.exist?(git_path)
+  lib_path = File.expand_path("../lib", __dir__)
+  $:.unshift(lib_path)
+end
+
+require 'derivator'
+
+curve = ARGV.first || 'secp256k1'
+seed_hex = STDIN.gets.chomp
+key = Derivator::Key.from_seed(seed_hex, curve.to_sym)
+puts "#{key.private_key_hex} #{key.chain_code_hex}"

data/exe/derivator_mnemonic

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+git_path = File.expand_path("../.git", __dir__)
+
+if File.exist?(git_path)
+  lib_path = File.expand_path("../lib", __dir__)
+  $:.unshift(lib_path)
+end
+
+require 'derivator'
+
+puts Derivator::Mnemonic.generate

data/exe/derivator_public_from_private

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+git_path = File.expand_path("../.git", __dir__)
+
+if File.exist?(git_path)
+  lib_path = File.expand_path("../lib", __dir__)
+  $:.unshift(lib_path)
+end
+
+require 'derivator'
+
+private_key = STDIN.gets.split.first
+curve = ARGV.first || 'secp256k1'
+key = Derivator::Key.from_hex(private_key, '', curve.to_sym)
+puts key.public_key_hex

data/exe/derivator_seed_from_mnemonic

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+git_path = File.expand_path("../.git", __dir__)
+
+if File.exist?(git_path)
+  lib_path = File.expand_path("../lib", __dir__)
+  $:.unshift(lib_path)
+end
+
+require 'derivator'
+
+mnemonic = STDIN.gets
+password = ARGV.first
+puts Derivator::Mnemonic.seed(mnemonic, password)

data/lib/derivator/key.rb

@@ -0,0 +1,300 @@
+require_relative 'refinements'
+
+module Derivator
+  # {https://github.com/satoshilabs/slips/blob/master/slip-0010.md SLIP10} key derivation.
+  class Key
+    # secp256k1 EC private key binary prefix when DER-encoded
+    SECP256K1_DER_PRIVATE_PREFIX = '303e020100301006072a8648ce3d020106052b8104000a042730250201010420'
+    # nist256p1 EC private key binary prefix when DER-encoded
+    NIST256P1_DER_PRIVATE_PREFIX = '3041020100301306072a8648ce3d020106082a8648ce3d030107042730250201010420'
+    # ed25519 EC private key binary prefix when DER-encoded
+    ED25519_DER_PRIVATE_PREFIX = '302e020100300506032b657004220420'
+    # ed25519 EC public key binary prefix when DER-encoded
+    ED25519_DER_PUBLIC_PREFIX = '302a300506032b65700321'
+
+    # secp256k1 BIP32/SLIP10 seed key
+    SECP256K1_SEED_KEY = 'Bitcoin seed'
+    # nist256p1 SLIP10 seed key
+    NIST256P1_SEED_KEY = 'Nist256p1 seed'
+    # ed25519 SLIP10 seed key
+    ED25519_SEED_KEY = 'ed25519 seed'
+
+    # secp256k1 largest valid private key
+    SECP256K1_LARGEST_KEY = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364140
+    # nist256p1 largest valid private key
+    NIST256P1_LARGEST_KEY = 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551
+    # ed25519 largest valid private key (unlimited)
+    ED25519_LARGEST_KEY = 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+
+    # @return [Symbol] EC curve used for the key (<code>:secp256k1</code>, <code>:nist256p1</code> or <code>:ed25519</code>).
+    attr_reader :curve
+
+    # @return [String] private key (in binary format).
+    attr_reader :private_key
+
+    # @return [String] chain code (in binary format).
+    attr_reader :chain_code
+
+    using Refinements
+
+    # Creates new key from private key and chain code hex strings.
+    #
+    # @param private_key_hex [String] private key hex string
+    # @param chain_code_hex [String] chain code hex string
+    # @param curve [Symbol] curve (<code>:secp256k1</code>, <code>:nist256p1</code> or <code>:ed25519</code>)
+    # @return [Key] new key
+    def self.from_hex(private_key_hex, chain_code_hex, curve = :secp256k1)
+      new(private_key_hex.from_hex, chain_code_hex.from_hex, curve)
+    end
+
+    # Creates new key from seed hex string.
+    #
+    # @param seed_hex [String] seed hex string
+    # @param curve [Symbol] curve (<code>:secp256k1</code>, <code>:nist256p1</code> or <code>:ed25519</code>)
+    # @return [Key] new key
+    def self.from_seed(seed_hex, curve = :secp256k1)
+      seed_bytes = seed_hex.from_hex
+      seed_key =
+        case curve
+        when :secp256k1
+          SECP256K1_SEED_KEY
+        when :nist256p1
+          NIST256P1_SEED_KEY
+        when :ed25519
+          ED25519_SEED_KEY
+        end
+
+      hmac =
+        OpenSSL::HMAC.hexdigest(
+          "SHA512",
+          seed_key,
+          seed_bytes
+        )
+
+      private_key_hex = hmac[0..63]
+      chain_code_hex = hmac[64..-1]
+      if valid_private_key?(private_key_hex, curve)
+        from_hex(private_key_hex, chain_code_hex, curve)
+      else
+        from_seed(hmac, curve)
+      end
+    end
+
+    # Checks private key for a particular curve (used internally).
+    # Primarily checks whether key value is less than order of the curve.
+    #
+    # @param private_key_hex [String] private key hex string
+    # @param curve [Symbol] curve (<code>:secp256k1</code>, <code>:nist256p1</code> or <code>:ed25519</code>)
+    # @return [true, false] whether the key is valid
+    def self.valid_private_key?(private_key_hex, curve = :secp256k1)
+      return false unless private_key_hex =~ /\A[a-f0-9]{64}\z/
+
+      largest_key =
+        case curve
+        when :secp256k1
+          SECP256K1_LARGEST_KEY
+        when :nist256p1
+          NIST256P1_LARGEST_KEY
+        when :ed25519
+          ED25519_LARGEST_KEY
+        end
+      private_key = private_key_hex.to_i(16)
+      private_key <= largest_key && (private_key > 0 || curve == :ed25519)
+    end
+
+    # Creates private key from binary data.
+    # Use {.from_hex} or {.from_seed} instead for convenience.
+    #
+    # @param private_key [String] private key (in binary format)
+    # @param chain_code [String] chain_code (in binary format)
+    # @param curve [Symbol] curve (<code>:secp256k1</code>, <code>:nist256p1</code> or <code>:ed25519</code>)
+    def initialize(private_key, chain_code, curve = :secp256k1)
+      @private_key = private_key.dup.freeze
+      @chain_code = chain_code.dup.freeze
+
+      unless %i[secp256k1 nist256p1 ed25519].include?(curve)
+        raise ArgumentError.new('curve must be :secp256k1, :nist256p1 or :ed25519')
+      end
+
+      @curve = curve
+    end
+
+    # Compares with another {Key}.
+    #
+    # @param other [Key] subject of comparison
+    # @return [true, false] whether {private_key}, {chain_code} and {curve} of
+    #   <code>other</code> matches <code>self</code>
+    def ==(other)
+      return false unless %i[private_key chain_code curve].all? { |m| other.respond_to?(m) }
+
+      private_key == other.private_key &&
+        chain_code == other.chain_code &&
+        curve == other.curve
+    end
+
+    # Chain code as hex string.
+    #
+    # @return [String]
+    def chain_code_hex
+      @chain_code_hex ||= @chain_code.to_hex.freeze
+    end
+
+    # {https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#key-identifiers BIP32 fingerprint}
+    # (first 4 bytes of HASH160 of public key) as hex string.
+    #
+    # @return [String]
+    def fingerprint
+      @fingerprint ||= public_key.hash160[0..3].to_hex
+    end
+
+    # Private key as hex string.
+    #
+    # @return [String]
+    def private_key_hex
+      @private_key_hex ||= @private_key.to_hex.freeze
+    end
+
+    # Public key (in binary format).
+    # Use {public_key_hex} for convenience.
+    #
+    # @return [String]
+    def public_key
+      @public_key ||= begin
+        case curve
+        when :ed25519
+          openssl_pkey.
+            public_to_der.
+            to_hex.
+            delete_prefix(ED25519_DER_PUBLIC_PREFIX).
+            from_hex.freeze
+        else
+          openssl_pkey.
+            public_key.
+            to_octet_string(:compressed).freeze
+        end
+      end
+    end
+
+    # Public key as hex string.
+    #
+    # @return [String]
+    def public_key_hex
+      @public_key_hex ||= public_key.to_hex.freeze
+    end
+
+    # Derive child key.
+    #
+    # @param path [String] derivation path, e.g. <code>'m/0/1'</code>,
+    #   <code>'5'</code>, <code>'0/3'</code>, <code>"m/0/3'/5'/1/2"</code>.
+    #   Use <code>'</code> for hardened keys.
+    def derive(path)
+      return self if path == 'm' || path.empty?
+      path = path.delete_prefix('m').delete_prefix('/')
+      path = path.split('/')
+
+      i_string = path.first
+      unless i_string =~ /\A[0-9]+'?\z/
+        raise ArgumentError.new("Wrong derivation segment: #{i_string.inspect}")
+      end
+      i = i_string.to_i
+      i += 2**31 if i_string[-1] == "'"
+
+      if curve == :ed25519 && i < 2**31
+        raise ArgumentError.new("Only hardened derivation supported with ED25519, got #{i_string} instead")
+      end
+
+      if curve != :ed25519
+        generator = openssl_group.generator
+      end
+
+      data =
+        if i >= 2**31
+          # Data for HMAC-SHA512(Key = cpar, Data = 0x00 || ser256(kpar) || ser32(i))
+          "00" + private_key_hex + ("%08x" % i)
+        else
+          # Data for HMAC-SHA512(Key = cpar, Data = serP(point(kpar)) || ser32(i))
+          generator.mul(private_key_hex.to_i(16)).to_octet_string(:compressed).to_hex + ("%08x" % i)
+        end
+      data = data.from_hex
+
+      hmac =
+        OpenSSL::HMAC.hexdigest(
+          "SHA512",
+          chain_code,
+          data
+        )
+      derived_private_key_hex = hmac[0..63]
+      derived_chain_code_hex = hmac[64..-1]
+
+      if curve != :ed25519
+        derived_private_key_hex, derived_chain_code_hex =
+          finish_derivation(derived_private_key_hex, derived_chain_code_hex, i)
+      end
+
+      new_key = self.class.from_hex(derived_private_key_hex, derived_chain_code_hex, curve)
+      new_key.derive(path[1..-1].join('/'))
+    end
+
+    # Exports key to PEM format.
+    #
+    # @return [String]
+    def to_pem
+      private_prefix =
+        case curve
+        when :secp256k1
+          SECP256K1_DER_PRIVATE_PREFIX
+        when :nist256p1
+          NIST256P1_DER_PRIVATE_PREFIX
+        when :ed25519
+          ED25519_DER_PRIVATE_PREFIX
+        end
+
+      der = (private_prefix + private_key_hex).from_hex
+      pem = <<~END
+        -----BEGIN PRIVATE KEY-----
+        #{der.to_base64.strip}
+        -----END PRIVATE KEY-----
+      END
+    end
+
+    # Creates {OpenSSL::PKey}[https://ruby-doc.org/stdlib-2.7.4/libdoc/openssl/rdoc/OpenSSL/PKey/EC/Point.html] instance.
+    #
+    # @return [OpenSSL::PKey::EC::Point]
+    def openssl_pkey
+      OpenSSL::PKey.read(to_pem)
+    end
+
+    # Creates {OpenSSL::PKey::EC::Group}[https://ruby-doc.org/stdlib-2.7.4/libdoc/openssl/rdoc/OpenSSL/PKey/EC/Group.html] instance for the key's {curve}.
+    #
+    # @return [OpenSSL::PKey::EC::Group]
+    def openssl_group
+      case curve
+      when :secp256k1
+        OpenSSL::PKey::EC::Group.new('secp256k1')
+      when :nist256p1
+        OpenSSL::PKey::EC::Group.new('prime256v1')
+      end
+    end
+
+    private
+
+    def finish_derivation(i_l_hex, i_r_hex, i)
+      group = openssl_group
+      i_l = i_l_hex.to_i(16)
+      new_key_int = (i_l + private_key_hex.to_i(16)) % group.order
+      if i_l >= group.order || new_key_int == 0
+        # let I = HMAC-SHA512(Key = cpar, Data = 0x01 || IR || ser32(i) and restart at step 2.
+        data = ("01" + i_r_hex + ("%08x" % i)).from_hex
+        hmac =
+          OpenSSL::HMAC.hexdigest(
+            "SHA512",
+            chain_code,
+            data
+          )
+        finish_derivation(hmac[0..63], hmac[64..-1], i)
+      else
+        ["%064x" % new_key_int, i_r_hex]
+      end
+    end
+  end
+end