eth 0.4.18 → 0.5.2

data/lib/eth/key/decrypter.rb

@@ -1,110 +1,146 @@
-require "json"
-require "scrypt"
-
-class Eth::Key::Decrypter
-  include Eth::Utils
-
-  def self.perform(data, password)
-    new(data, password).perform
-  end
-
-  def initialize(data, password)
-    @data = JSON.parse(data)
-    @password = password
-  end
-
-  def perform
-    derive_key password
-    check_macs
-    bin_to_hex decrypted_data
-  end
+# 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::Decrypter} class to handle PBKDF2-SHA-256 decryption.
+  class Key::Decrypter
+
+    # Provides a specific decrypter error if decryption fails.
+    class DecrypterError < StandardError; end
+
+    # Class method {Eth::Key::Decrypter.perform} to perform an keystore
+    # decryption.
+    #
+    # @param data [JSON] encryption data including cypherkey.
+    # @param password [String] password to decrypt the key.
+    # @return [Eth::Key] decrypted key-pair.
+    def self.perform(data, password)
+      new(data, password).perform
+    end
 
-  private
+    # Constructor of the {Eth::Key::Decrypter} class for secret key
+    # decryption. Should not be used; use {Eth::Key::Decrypter.perform}
+    # instead.
+    #
+    # @param data [JSON] encryption data including cypherkey.
+    # @param password [String] password to decrypt the key.
+    def initialize(data, password)
+      data = JSON.parse(data) if data.is_a? String
+      @data = data
+      @password = password
+    end
 
-  attr_reader :data, :key, :password
+    # Method to decrypt key using password.
+    #
+    # @return [Eth::Key] decrypted key.
+    def perform
+      derive_key password
+      check_macs
+      private_key = Util.bin_to_hex decrypted_data
+      Eth::Key.new priv: private_key
+    end
 
-  def derive_key(password)
-    case kdf
-    when "pbkdf2"
-      @key = OpenSSL::PKCS5.pbkdf2_hmac(password, salt, iterations, key_length, digest)
-    when "scrypt"
-      # OpenSSL 1.1 inclues OpenSSL::KDF.scrypt, but it is not available usually, otherwise we could do: OpenSSL::KDF.scrypt(password, salt: salt, N: n, r: r, p: p, length: key_length)
-      @key = SCrypt::Engine.scrypt(password, salt, n, r, p, key_length)
-    else
-      raise "Unsupported key derivation function: #{kdf}!"
+    private
+
+    attr_reader :data
+    attr_reader :key
+    attr_reader :password
+
+    def derive_key(password)
+      case kdf
+      when "pbkdf2"
+        @key = OpenSSL::PKCS5.pbkdf2_hmac(password, salt, iterations, key_length, digest)
+      when "scrypt"
+        @key = SCrypt::Engine.scrypt(password, salt, n, r, p, key_length)
+      else
+        raise DecrypterError, "Unsupported key derivation function: #{kdf}!"
+      end
     end
-  end
 
-  def check_macs
-    mac1 = keccak256(key[(key_length / 2), key_length] + ciphertext)
-    mac2 = hex_to_bin crypto_data["mac"]
+    def check_macs
+      mac1 = Util.keccak256(key[(key_length / 2), key_length] + ciphertext)
+      mac2 = Util.hex_to_bin crypto_data["mac"]
 
-    if mac1 != mac2
-      raise "Message Authentications Codes do not match!"
+      if mac1 != mac2
+        raise DecrypterError, "Message Authentications Codes do not match!"
+      end
     end
-  end
 
-  def decrypted_data
-    @decrypted_data ||= cipher.update(ciphertext) + cipher.final
-  end
+    def decrypted_data
+      @decrypted_data ||= cipher.update(ciphertext) + cipher.final
+    end
 
-  def crypto_data
-    @crypto_data ||= data["crypto"] || data["Crypto"]
-  end
+    def crypto_data
+      @crypto_data ||= data["crypto"] || data["Crypto"]
+    end
 
-  def ciphertext
-    hex_to_bin crypto_data["ciphertext"]
-  end
+    def ciphertext
+      Util.hex_to_bin crypto_data["ciphertext"]
+    end
 
-  def cipher_name
-    "aes-128-ctr"
-  end
+    def cipher_name
+      "aes-128-ctr"
+    end
 
-  def cipher
-    @cipher ||= OpenSSL::Cipher.new(cipher_name).tap do |cipher|
-      cipher.decrypt
-      cipher.key = key[0, (key_length / 2)]
-      cipher.iv = iv
+    def cipher
+      @cipher ||= OpenSSL::Cipher.new(cipher_name).tap do |cipher|
+        cipher.decrypt
+        cipher.key = key[0, (key_length / 2)]
+        cipher.iv = iv
+      end
     end
-  end
 
-  def iv
-    hex_to_bin crypto_data["cipherparams"]["iv"]
-  end
+    def iv
+      Util.hex_to_bin crypto_data["cipherparams"]["iv"]
+    end
 
-  def salt
-    hex_to_bin crypto_data["kdfparams"]["salt"]
-  end
+    def salt
+      Util.hex_to_bin crypto_data["kdfparams"]["salt"]
+    end
 
-  def iterations
-    crypto_data["kdfparams"]["c"].to_i
-  end
+    def iterations
+      crypto_data["kdfparams"]["c"].to_i
+    end
 
-  def kdf
-    crypto_data["kdf"]
-  end
+    def kdf
+      crypto_data["kdf"]
+    end
 
-  def key_length
-    crypto_data["kdfparams"]["dklen"].to_i
-  end
+    def key_length
+      crypto_data["kdfparams"]["dklen"].to_i
+    end
 
-  def n
-    crypto_data["kdfparams"]["n"].to_i
-  end
+    def n
+      crypto_data["kdfparams"]["n"].to_i
+    end
 
-  def r
-    crypto_data["kdfparams"]["r"].to_i
-  end
+    def r
+      crypto_data["kdfparams"]["r"].to_i
+    end
 
-  def p
-    crypto_data["kdfparams"]["p"].to_i
-  end
+    def p
+      crypto_data["kdfparams"]["p"].to_i
+    end
 
-  def digest
-    OpenSSL::Digest.new digest_name
-  end
+    def digest
+      OpenSSL::Digest.new digest_name
+    end
 
-  def digest_name
-    "sha256"
+    def digest_name
+      "sha256"
+    end
   end
 end

data/lib/eth/key/encrypter.rb

@@ -1,126 +1,207 @@
-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. Should not be used; use {Eth::Key::Encrypter.perform}
+    # instead.
+    #
+    # @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.new(priv: key) if key.is_a? String
+      @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