eth 0.4.18 → 0.5.0

data/lib/eth/key/encrypter.rb

@@ -1,126 +1,205 @@
-require "json"
-require "securerandom"
+# Copyright (c) 2016-2022 The Ruby-Eth Contributors
+#
+# 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.
+
+# Provides the `Eth` module.
+module Eth
+
+  # The Eth::Key::Encrypter class to handle PBKDF2-SHA-256 encryption.
+  class Key::Encrypter
+
+    # Provides a specific encrypter error if decryption fails.
+    class EncrypterError < StandardError; end
+
+    # Class method `Eth::Key::Encrypter.perform` to performa an key-store
+    # encryption.
+    #
+    # @param key [Eth::Key] representing a secret key-pair used for encryption
+    # @param options [Hash] the options to encrypt with
+    # @option options [String] :kdf key derivation function defaults to pbkdf2
+    # @option options [String] :id uuid given to the secret key
+    # @option options [String] :iterations number of iterations for the hash function
+    # @option options [String] :salt passed to PBKDF
+    # @option options [String] :iv 128-bit initialisation vector for the cipher
+    # @option options [Integer] :parallelization parallelization factor for scrypt, defaults to 8
+    # @option options [Integer] :block_size for scrypt, defaults to 1
+    # @return [JSON] formatted with encrypted key (cyphertext) and [other identifying data](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition#pbkdf2-sha-256)
+    def self.perform(key, password, options = {})
+      new(key, options).perform(password)
+    end
 
-class Eth::Key::Encrypter
-  include Eth::Utils
+    # Constructor of the `Eth::Key::Encrypter` class for secret key
+    # encryption.
+    #
+    # @param key [Eth::Key] representing a secret key-pair used for encryption
+    # @param options [Hash] the options to encrypt with
+    # @option options [String] :kdf key derivation function defaults to pbkdf2
+    # @option options [String] :id uuid given to the secret key
+    # @option options [String] :iterations number of iterations for the hash function
+    # @option options [String] :salt passed to PBKDF
+    # @option options [String] :iv 128-bit initialisation vector for the cipher
+    # @option options [Integer] :parallelization parallelization factor for scrypt, defaults to 8
+    # @option options [Integer] :block_size for scrypt, defaults to 1
+    def initialize(key, options = {})
+      @key = key
+      @options = options
+
+      # the key derivation functions default to pbkdf2 if no option is specified
+      # however, if an option is given then it must be either pbkdf2 or scrypt
+      if kdf != "scrypt" && kdf != "pbkdf2"
+        raise EncrypterError, "Unsupported key derivation function: #{kdf}!"
+      end
+    end
 
-  def self.perform(key, password, options = {})
-    new(key, options).perform(password)
-  end
+    # Encrypt the key with a given password.
+    #
+    # @param password [String] a secret key used for encryption
+    # @return [String] a json-formatted keystore string.
+    def perform(password)
+      derive_key password
+      encrypt
+      data.to_json
+    end
 
-  def initialize(key, options = {})
-    @key = key
-    @options = options
-  end
+    # Output containing the encrypted key and
+    # [other identifying data](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition#pbkdf2-sha-256)
+    #
+    # @return [Hash] the encrypted keystore data.
+    def data
+      # default to pbkdf2
+      kdfparams = if kdf == "scrypt"
+          {
+            dklen: 32,
+            n: iterations,
+            p: parallelization,
+            r: block_size,
+            salt: Util.bin_to_hex(salt),
+          }
+        else
+          {
+            c: iterations,
+            dklen: 32,
+            prf: prf,
+            salt: Util.bin_to_hex(salt),
+          }
+        end
+
+      {
+        crypto: {
+          cipher: cipher_name,
+          cipherparams: {
+            iv: Util.bin_to_hex(iv),
+          },
+          ciphertext: Util.bin_to_hex(encrypted_key),
+          kdf: kdf,
+          kdfparams: kdfparams,
+          mac: Util.bin_to_hex(mac),
+        },
+        id: id,
+        version: 3,
+      }
+    end
 
-  def perform(password)
-    derive_key password
-    encrypt
+    private
 
-    data.to_json
-  end
+    attr_reader :derived_key, :encrypted_key, :key, :options
 
-  def data
-    {
-      crypto: {
-        cipher: cipher_name,
-        cipherparams: {
-          iv: bin_to_hex(iv),
-        },
-        ciphertext: bin_to_hex(encrypted_key),
-        kdf: "pbkdf2",
-        kdfparams: {
-          c: iterations,
-          dklen: 32,
-          prf: prf,
-          salt: bin_to_hex(salt),
-        },
-        mac: bin_to_hex(mac),
-      },
-      id: id,
-      version: 3,
-    }.tap do |data|
-      data[:address] = address unless options[:skip_address]
+    def cipher
+      @cipher ||= OpenSSL::Cipher.new(cipher_name).tap do |cipher|
+        cipher.encrypt
+        cipher.iv = iv
+        cipher.key = derived_key[0, (key_length / 2)]
+      end
     end
-  end
 
-  def id
-    @id ||= options[:id] || SecureRandom.uuid
-  end
-
-  private
+    def digest
+      @digest ||= OpenSSL::Digest.new digest_name
+    end
 
-  attr_reader :derived_key, :encrypted_key, :key, :options
+    def derive_key(password)
+      if kdf == "scrypt"
+        @derived_key = SCrypt::Engine.scrypt(password, salt, iterations, block_size, parallelization, key_length)
+      else
+        @derived_key = OpenSSL::PKCS5.pbkdf2_hmac(password, salt, iterations, key_length, digest)
+      end
+    end
 
-  def cipher
-    @cipher ||= OpenSSL::Cipher.new(cipher_name).tap do |cipher|
-      cipher.encrypt
-      cipher.iv = iv
-      cipher.key = derived_key[0, (key_length / 2)]
+    def encrypt
+      @encrypted_key = cipher.update(Util.hex_to_bin key.private_hex) + cipher.final
     end
-  end
 
-  def digest
-    @digest ||= OpenSSL::Digest.new digest_name
-  end
+    def mac
+      Util.keccak256(derived_key[(key_length / 2), key_length] + encrypted_key)
+    end
 
-  def derive_key(password)
-    @derived_key = OpenSSL::PKCS5.pbkdf2_hmac(password, salt, iterations, key_length, digest)
-  end
+    def kdf
+      options[:kdf] || "pbkdf2"
+    end
 
-  def encrypt
-    @encrypted_key = cipher.update(hex_to_bin key) + cipher.final
-  end
+    def cipher_name
+      "aes-128-ctr"
+    end
 
-  def mac
-    keccak256(derived_key[(key_length / 2), key_length] + encrypted_key)
-  end
+    def digest_name
+      "sha256"
+    end
 
-  def cipher_name
-    "aes-128-ctr"
-  end
+    def prf
+      "hmac-#{digest_name}"
+    end
 
-  def digest_name
-    "sha256"
-  end
+    def key_length
+      32
+    end
 
-  def prf
-    "hmac-#{digest_name}"
-  end
+    def salt_length
+      32
+    end
 
-  def key_length
-    32
-  end
+    def iv_length
+      16
+    end
 
-  def salt_length
-    32
-  end
+    def id
+      @id ||= options[:id] || SecureRandom.uuid
+    end
 
-  def iv_length
-    16
-  end
+    def iterations
+      options[:iterations] || 262_144
+    end
 
-  def iterations
-    options[:iterations] || 262_144
-  end
+    def salt
+      @salt ||= if options[:salt]
+          Util.hex_to_bin options[:salt]
+        else
+          SecureRandom.random_bytes(salt_length)
+        end
+    end
 
-  def salt
-    @salt ||= if options[:salt]
-        hex_to_bin options[:salt]
-      else
-        SecureRandom.random_bytes(salt_length)
-      end
-  end
+    def iv
+      @iv ||= if options[:iv]
+          Util.hex_to_bin options[:iv]
+        else
+          SecureRandom.random_bytes(iv_length)
+        end
+    end
 
-  def iv
-    @iv ||= if options[:iv]
-        hex_to_bin options[:iv]
-      else
-        SecureRandom.random_bytes(iv_length)
-      end
-  end
+    def parallelization
+      options[:parallelization] || 8
+    end
 
-  def address
-    Eth::Key.new(priv: key).address
+    def block_size
+      options[:block_size] || 1
+    end
   end
 end

data/lib/eth/key.rb

@@ -1,78 +1,162 @@
+# Copyright (c) 2016-2022 The Ruby-Eth Contributors
+#
+# 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 "json"
+require "openssl"
+require "rbsecp256k1"
+require "scrypt"
+require "securerandom"
+
+# Provides the `Eth` module.
 module Eth
+
+  # The `Eth::Key` class to handle Secp256k1 private/public key-pairs.
   class Key
+
+    # The Eth::Key::Decrypter class to handle PBKDF2-SHA-256 decryption.
     autoload :Decrypter, "eth/key/decrypter"
+
+    # The Eth::Key::Encrypter class to handle PBKDF2-SHA-256 encryption.
     autoload :Encrypter, "eth/key/encrypter"
 
-    attr_reader :private_key, :public_key
+    # The `Secp256k1::PrivateKey` of the `Eth::Key` pair.
+    attr_reader :private_key
 
-    def self.encrypt(key, password)
-      key = new(priv: key) unless key.is_a?(Key)
+    # The `Secp256k1::PublicKey` of the `Eth::Key` pair.
+    attr_reader :public_key
 
-      Encrypter.perform key.private_hex, password
-    end
+    # Constructor of the `Eth::Key` class. Creates a new random key-pair
+    # if no `priv` key is provided.
+    #
+    # @param priv [String] binary string of private key data (optional).
+    def initialize(priv: nil)
 
-    def self.decrypt(data, password)
-      priv = Decrypter.perform data, password
-      new priv: priv
-    end
+      # Creates a new, randomized libsecp256k1 context.
+      ctx = Secp256k1::Context.new context_randomization_bytes: SecureRandom.random_bytes(32)
 
-    def self.personal_recover(message, signature)
-      bin_signature = Utils.hex_to_bin(signature).bytes.rotate(-1).pack("c*")
-      OpenSsl.recover_compact(Utils.keccak256(Utils.prefix_message(message)), bin_signature)
-    end
+      # Creates a new random key pair (public, private).
+      key = ctx.generate_key_pair
 
-    def initialize(priv: nil)
-      @private_key = MoneyTree::PrivateKey.new key: priv
-      @public_key = MoneyTree::PublicKey.new private_key, compressed: false
-    end
+      unless priv.nil?
 
-    def private_hex
-      private_key.to_hex
-    end
+        # Converts hex private keys to binary strings.
+        priv = Util.hex_to_bin priv if Util.is_hex? priv
 
-    def public_bytes
-      public_key.to_bytes
+        # Creates a keypair from existing private key data.
+        key = ctx.key_pair_from_private_key priv
+      end
+
+      # Sets the attributes.
+      @private_key = key.private_key
+      @public_key = key.public_key
     end
 
-    def public_hex
-      public_key.to_hex
+    # Signs arbitrary data without validation. Should not be used unless really
+    # desired. See also: personal_sign, sign_typed_data.
+    #
+    # @param blob [String] that arbitrary data to be signed.
+    # @param chain_id [Integer] the chain id the signature should be generated on.
+    # @return [String] a hexa-decimal signature.
+    def sign(blob, chain_id = nil)
+      context = Secp256k1::Context.new
+      compact, recovery_id = context.sign_recoverable(@private_key, blob).compact
+      signature = compact.bytes
+      v = Chain.to_v recovery_id, chain_id
+      is_leading_zero = true
+      [v].pack("N").unpack("C*").each do |byte|
+        is_leading_zero = false if byte > 0 and is_leading_zero
+        signature.append byte unless is_leading_zero and byte === 0
+      end
+      Util.bin_to_hex signature.pack "c*"
     end
 
-    def address
-      Utils.public_key_to_address public_hex
+    # Prefixes a message with "\x19Ethereum Signed Message:" and signs
+    # it in the common way used by many web3 wallets. Complies with
+    # EIP-191 prefix 0x19 and version byte 0x45 (E).
+    #
+    # @param message [String] the message string to be prefixed and signed.
+    # @param chain_id [Integer] the chain id the signature should be generated on.
+    # @return [String] an EIP-191 conform, hexa-decimal signature.
+    def personal_sign(message, chain_id = nil)
+      prefixed_message = Signature.prefix_message message
+      hashed_message = Util.keccak256 prefixed_message
+      sign hashed_message, chain_id
     end
 
-    alias_method :to_address, :address
+    # Prefixes, hashes, and signes a typed data structure in the common
+    # way used by many web3 wallets. Complies with EIP-191 prefix 0x19
+    # and EIP-712 version byte 0x01. Supports `V3`, `V4`.
+    #
+    # @param typed_data [Array] all the data in the typed data structure to be signed.
+    # @param chain_id [Integer] the chain id the signature should be generated on.
+    # @return [String] an EIP-712 conform, hexa-decimal signature.
+    def sign_typed_data(typed_data, chain_id = nil)
+      hash_to_sign = Eip712.hash typed_data
+      sign hash_to_sign, chain_id
+    end
 
-    def sign(message)
-      sign_hash message_hash(message)
+    # Converts the private key data into a hexa-decimal string.
+    #
+    # @return [String] private key as hexa-decimal string.
+    def private_hex
+      Util.bin_to_hex @private_key.data
     end
 
-    def sign_hash(hash)
-      loop do
-        signature = OpenSsl.sign_compact hash, private_hex, public_hex
-        return signature if valid_s? signature
-      end
+    # Exports the private key bytes in a wrapper function to maintain
+    # backward-compatibility with older versions of `Eth::Key`.
+    #
+    # @return [String] private key as packed byte-string.
+    def private_bytes
+      @private_key.data
     end
 
-    def verify_signature(message, signature)
-      hash = message_hash(message)
-      public_hex == OpenSsl.recover_compact(hash, signature)
+    # Converts the public key data into an uncompressed
+    # hexa-decimal string.
+    #
+    # @return [String] public key as uncompressed hexa-decimal string.
+    def public_hex
+      Util.bin_to_hex @public_key.uncompressed
     end
 
-    def personal_sign(message)
-      Utils.bin_to_hex(sign(Utils.prefix_message(message)).bytes.rotate(1).pack("c*"))
+    # Converts the public key data into an compressed
+    # hexa-decimal string.
+    #
+    # @return [String] public key as compressed hexa-decimal string.
+    def public_hex_compressed
+      Util.bin_to_hex @public_key.compressed
     end
 
-    private
+    # Exports the uncompressed public key bytes in a wrapper function to
+    # maintain backward-compatibility with older versions of `Eth::Key`.
+    #
+    # @return [String] uncompressed public key as packed byte-string.
+    def public_bytes
+      @public_key.uncompressed
+    end
 
-    def message_hash(message)
-      Utils.keccak256 message
+    # Exports the compressed public key bytes.
+    #
+    # @return [String] compressed public key as packed byte-string.
+    def public_bytes_compressed
+      @public_key.compressed
     end
 
-    def valid_s?(signature)
-      s_value = Utils.v_r_s_for(signature).last
-      s_value <= Secp256k1::N / 2 && s_value != 0
+    # Exports the checksummed public address.
+    #
+    # @return [Eth::Address] compressed address as packed hex prefixed string.
+    def address
+      Util.public_key_to_address public_bytes
     end
   end
 end

data/lib/eth/signature.rb

@@ -0,0 +1,160 @@
+# Copyright (c) 2016-2022 The Ruby-Eth Contributors
+#
+# 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 "rbsecp256k1"
+
+# Provides the `Eth` module.
+module Eth
+
+  # Defines handy tools for verifying and recovering signatures.
+  module Signature
+    extend self
+
+    # Provides a special signature error if signature is invalid.
+    class SignatureError < StandardError; end
+
+    # EIP-191 prefix byte 0x19
+    EIP191_PREFIX_BYTE = "\x19".freeze
+
+    # EIP-712 version byte 0x01
+    EIP712_VERSION_BYTE = "\x01".freeze
+
+    # Prefix message as per EIP-191 with 0x19 to ensure the data is not
+    # valid RLP and thus not mistaken for a transaction.
+    # EIP-191 Version byte: 0x45 (E)
+    # ref: https://eips.ethereum.org/EIPS/eip-191
+    #
+    # @param message [String] the message string to be prefixed.
+    # @return [String] an EIP-191 prefixed string
+    def prefix_message(message)
+      "#{EIP191_PREFIX_BYTE}Ethereum Signed Message:\n#{message.size}#{message}"
+    end
+
+    # Dissects a signature blob of 65 bytes into its r, s, and v values.
+    #
+    # @param signature [String] a Secp256k1 signature.
+    # @return [String, String, String] the r, s, and v values.
+    # @raise [SignatureError] if signature is of unknown size.
+    def dissect(signature)
+      signature = Util.bin_to_hex signature unless Util.is_hex? signature
+      signature = Util.remove_hex_prefix signature
+      if signature.size < 130
+        raise SignatureError, "Unknown signature length #{signature.size}!"
+      end
+      r = signature[0, 64]
+      s = signature[64, 64]
+      v = signature[128..]
+      return r, s, v
+    end
+
+    # Recovers a signature from arbitrary data without validation on a given chain.
+    #
+    # @param blob [String] that arbitrary data to be recovered.
+    # @param signature [String] the hex string containing the signature.
+    # @param chain_id [Integer] the chain ID the signature should be recovered from.
+    # @return [String] a hexa-decimal, uncompressed public key.
+    # @raise [SignatureError] if signature is of invalid size or invalid v.
+    def recover(blob, signature, chain_id = Chain::ETHEREUM)
+      context = Secp256k1::Context.new
+      r, s, v = dissect signature
+      v = v.to_i(16)
+      raise SignatureError, "Invalid signature v byte #{v} for chain ID #{chain_id}!" if v < chain_id
+      recovery_id = Chain.to_recovery_id v, chain_id
+      signature_rs = Util.hex_to_bin "#{r}#{s}"
+      recoverable_signature = context.recoverable_signature_from_compact signature_rs, recovery_id
+      public_key = recoverable_signature.recover_public_key blob
+      Util.bin_to_hex public_key.uncompressed
+    end
+
+    # Recovers a public key from a prefixed, personal message and
+    # a signature on a given chain. (EIP-191)
+    #
+    # @param message [String] the message string.
+    # @param signature [String] the hex string containing the signature.
+    # @param chain_id [Integer] the chain ID the signature should be recovered from.
+    # @return [String] a hexa-decimal, uncompressed public key.
+    def personal_recover(message, signature, chain_id = Chain::ETHEREUM)
+      prefixed_message = prefix_message message
+      hashed_message = Util.keccak256 prefixed_message
+      recover hashed_message, signature, chain_id
+    end
+
+    # Recovers a public key from a typed data structure and a signature
+    # on a given chain. (EIP-712)
+    #
+    # @param typed_data [Array] all the data in the typed data structure to be recovered.
+    # @param signature [String] the hex string containing the signature.
+    # @param chain_id [Integer] the chain ID the signature should be recovered from.
+    # @return [String] a hexa-decimal, uncompressed public key.
+    def recover_typed_data(typed_data, signature, chain_id = Chain::ETHEREUM)
+      hash_to_sign = Eip712.hash typed_data
+      recover hash_to_sign, signature, chain_id
+    end
+
+    # Verifies a signature for a given public key or address.
+    #
+    # @param blob [String] that arbitrary data to be verified.
+    # @param signature [String] the hex string containing the signature.
+    # @param public_key [String] either a public key or an Ethereum address.
+    # @param chain_id [Integer] the chain ID used to sign.
+    # @return [Boolean] true if signature matches provided public key.
+    # @raise [SignatureError] if it cannot determine the type of data or public key.
+    def verify(blob, signature, public_key, chain_id = Chain::ETHEREUM)
+      recovered_key = nil
+      if blob.instance_of? Array or blob.instance_of? Hash
+
+        # recover Array from sign_typed_data
+        recovered_key = recover_typed_data blob, signature, chain_id
+      elsif blob.instance_of? String and blob.encoding != Encoding::ASCII_8BIT
+
+        # recover message from personal_sign
+        recovered_key = personal_recover blob, signature, chain_id
+      elsif blob.instance_of? String and (Util.is_hex? blob or blob.encoding == Encoding::ASCII_8BIT)
+
+        # if nothing else, recover from arbitrary signature
+        recovered_key = recover blob, signature, chain_id
+      end
+
+      # raise if we cannot determine the data format
+      raise SignatureError, "Unknown data format to verify: #{blob}" if recovered_key.nil?
+
+      if public_key.instance_of? Address
+
+        # recovering using an Eth::Address
+        address = public_key.to_s
+        recovered_address = Util.public_key_to_address(recovered_key).to_s
+        return address == recovered_address
+      elsif public_key.instance_of? Secp256k1::PublicKey
+
+        # recovering using an Secp256k1::PublicKey
+        public_hex = Util.bin_to_hex public_key.uncompressed
+        return public_hex == recovered_key
+      elsif public_key.size == 42
+
+        # recovering using an address String
+        address = Address.new(public_key).to_s
+        recovered_address = Util.public_key_to_address(recovered_key).to_s
+        return address == recovered_address
+      elsif public_key.size == 130
+
+        # recovering using an uncompressed public key String
+        return public_key == recovered_key
+      else
+
+        # raise if we cannot determine the public key format used
+        raise SignatureError, "Invalid public key or address supplied #{public_key}!"
+      end
+    end
+  end
+end