izokatu 0.1.1

data/lib/izokatu.rb

@@ -0,0 +1,423 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'rbnacl'
+require 'ecies'
+require 'base64'
+
+require 'contracts'
+# Deprecated warnings are disabled, because contracts raising those.
+# Make patch to contracts or use more updated tools, like, Sorbet.
+Warning[:deprecated] = false
+
+require_relative 'izokatu/izokatu_elements_requires'
+
+# Main module to work with.
+module Izokatu
+  include Contracts
+
+  class << self
+    prepend Izokatu::Helpers
+
+    # @return [Symbol] library used for encryption/decryption
+    attr_reader :via
+    # @return [Symbol] mode of encryption/decryption
+    attr_reader :mode
+    # @return [Symbol] action to execute
+    attr_reader :action
+    # @return [Symbol] OpenSSL public key cipher type
+    attr_reader :asym_cipher_type
+    # @return [Symbol] alias of Izokatu exporter
+    attr_reader :exporter
+    # @return [Symbol] alias of Izokatu importer
+    attr_reader :importer
+    # @return [String] OpenSSL private key cipher
+    # @note also used for OpenSSL public key ec key generation
+    attr_reader :cipher
+    # @return [Hash] options from user merged with default
+    attr_reader :options
+
+    # Default options for Izokatu call
+    DEFAULT_OPTIONS = {
+      via: :rbnacl,
+      mode: :private_key,
+      action: :encryption,
+      asym_cipher_type: :ec,
+      exporter: :function,
+      importer: :function,
+      cipher: 'secp521r1',
+      encrypted_data_filename: 'encrypted_data',
+      decrypter_params_filename: 'decrypter_params',
+      delete_imported: false
+    }.freeze
+
+    # Map of exporters and their symbol aliases
+    EXPORTER_MAPPING = {
+      function: FunctionExporter,
+      file: FileExporter,
+      stdout: StdoutExporter
+    }.freeze
+
+    # Map of importers and their symbol aliases
+    IMPORTER_MAPPING = {
+      function: FunctionImporter,
+      file: FileImporter
+    }.freeze
+
+    Contract Contracts::HashOf[Symbol, Any] =>
+             Contracts::HashOf[Symbol, Any]
+    # Public method to work with
+    #
+    # @param options [Hash] options from user
+    #
+    # @return [Hash] Encrypted/decrypted data with params or public/private keys
+    #
+    # @since 0.1.0
+    # @api public
+    #
+    # @example RbNaCl private key cryptography
+    #   encrypted_data = Izokatu.call(clear_data_string: 'Some data')
+    #   Izokatu.call(action: :decryption, **encrypted_data)
+    #   => {:decrypted_data_string=>"Some data"}
+    #
+    # @example RbNaCl public key cryptography
+    #   keypair1 = Izokatu.call(action: :keys_generation, mode: :public_key)
+    #   keypair2 = Izokatu.call(action: :keys_generation, mode: :public_key)
+    #   encrypted_data = Izokatu.call(
+    #     clear_data_string: 'Some data',
+    #     mode: :public_key,
+    #     public_key: keypair1[:public_key],
+    #     private_key: keypair2[:private_key]
+    #   )
+    #   Izokatu.call(
+    #     action: :decryption,
+    #     mode: :public_key,
+    #     **encrypted_data,
+    #     public_key: keypair2[:public_key],
+    #     private_key: keypair1[:private_key]
+    #   )
+    #   => {:decrypted_data_string=>"Some data"}
+    #
+    # @example OpenSSL private key cryptography
+    #   encrypted_data = Izokatu.call(
+    #     clear_data_string: 'Some data',
+    #     via: :openssl,
+    #     cipher: 'AES-256-GCM'
+    #   )
+    #   Izokatu.call(
+    #     action: :decryption,
+    #     **encrypted_data,
+    #     via: :openssl,
+    #     cipher: 'AES-256-GCM'
+    #   )
+    #   => {:decrypted_data_string=>"Some data"}
+    #
+    # @example OpenSSL EC public key cryptography
+    #   keypair_options = {
+    #     action: :keys_generation,
+    #     mode: :public_key,
+    #     via: :openssl
+    #   }
+    #   keypair1 = Izokatu.call(keypair_options)
+    #   keypair2 = Izokatu.call(keypair_options)
+    #   encrypted_data = Izokatu.call(
+    #     clear_data_string: 'Some data',
+    #     mode: :public_key,
+    #     via: :openssl,
+    #     public_key:
+    #     keypair1[:public_key],
+    #     private_key: keypair2[:private_key]
+    #   )
+    #   Izokatu.call(
+    #     action: :decryption,
+    #     mode: :public_key,
+    #     via: :openssl,
+    #     **encrypted_data,
+    #     public_key: keypair2[:public_key],
+    #     private_key: keypair1[:private_key]
+    #   )
+    #   => {:decrypted_data_string=>"Some data"}
+    #
+    # @example OpenSSL RSA public key cryptography
+    #   keypair_options = {
+    #     action: :keys_generation,
+    #     mode: :public_key,
+    #     via: :openssl,
+    #     asym_cipher_type: :rsa,
+    #     bit_number: 4096
+    #   }
+    #   keypair1 = Izokatu.call(keypair_options)
+    #   keypair2 = Izokatu.call(keypair_options)
+    #   encrypted_data = Izokatu.call(
+    #     clear_data_string: 'Some data',
+    #     mode: :public_key,
+    #     via: :openssl,
+    #     public_key: keypair1[:public_key],
+    #     private_key: keypair2[:private_key],
+    #     asym_cipher_type: :rsa
+    #   )
+    #   Izokatu.call(
+    #     action: :decryption,
+    #     mode: :public_key,
+    #     via: :openssl,
+    #     **encrypted_data,
+    #     public_key: keypair2[:public_key],
+    #     private_key: keypair1[:private_key],
+    #     asym_cipher_type: :rsa
+    #   )
+    #   => {:decrypted_data_string=>"Some data"}
+    def call(**options)
+      initialize!(options)
+      perform
+    end
+
+    private
+
+    Contract Contracts::HashOf[Symbol, Any] => Any
+    # Initializing Izokatu variables
+    #
+    # @param options (#options)
+    #
+    # @since 0.1.0
+    def initialize!(options)
+      options = merge_options!(options)
+      @via = options[:via]
+      @mode = options[:mode]
+      @action = options[:action]
+      @asym_cipher_type = options[:asym_cipher_type]
+      @exporter = options[:exporter]
+      @importer = options[:importer]
+      @cipher = format_cipher(options[:cipher])
+      @options = options
+    end
+
+    Contract Contracts::HashOf[Symbol, Any] =>
+             Contracts::HashOf[Symbol, Any]
+    # Merging user option with default
+    #
+    # @param options [Hash] options from user
+    #
+    # @return [Hash] user options merged with default
+    #
+    # @since 0.1.0
+    def merge_options!(options)
+      options ? DEFAULT_OPTIONS.merge(options) : DEFAULT_OPTIONS
+    end
+
+    Contract String => String
+    # Formatting name of OpenSSL private key ciphers
+    #
+    # @param cipher [String] cipher name from user
+    #
+    # @return [String] formatted cipher name
+    #
+    # @since 0.1.0
+    def format_cipher(cipher)
+      Openssl::PKEY_CIPHERS.include?(cipher) ? cipher.upcase : cipher
+    end
+
+    Contract None => Contracts::HashOf[Symbol, Any]
+    # Verifying and processing merged options
+    #
+    # @return [Hash] Encrypted/decrypted data with params or public/private keys
+    #
+    # @since 0.1.0
+    def perform
+      verify_izokatu_options!
+      verify_exporter_class!
+      verify_importer_class!
+      verify_izokatu_cipher!
+      select_exporter_class!
+      select_importer_class!
+      process_izokatu_options!
+    end
+
+    # Verifying options value
+    #
+    # @raise [RuntimeError] if option value is unknown
+    #
+    # @since 0.1.0
+    def verify_izokatu_options!
+      raise 'ERROR: Unknown library!' unless %i[openssl rbnacl].include?(via)
+      raise 'ERROR: Unknown mode!' unless %i[private_key public_key].include?(mode)
+      raise 'ERROR: Unknown action!' unless %i[encryption decryption keys_generation].include?(action)
+      raise 'ERROR: Unknown asym_cipher_type!' unless %i[ec rsa].include?(asym_cipher_type)
+    end
+
+    # Verifying exporter alias
+    #
+    # @raise [RuntimeError] if exporter alias is unknown
+    #
+    # @since 0.1.0
+    def verify_exporter_class!
+      raise 'ERROR: Unknown exporter!' unless %i[stdout file function].include?(exporter)
+    end
+
+    # Verifying importer alias
+    #
+    # @raise [RuntimeError] if importer alias is unknown
+    #
+    # @since 0.1.0
+    def verify_importer_class!
+      raise 'ERROR: Unknown importer!' unless %i[file function].include?(importer)
+    end
+
+    # Verifying cipher
+    #
+    # @raise [RuntimeError] if cipher name is unknowm
+    #
+    # @note also raising exception if cipher is using unsupported WRAP mode
+    #
+    # @since 0.1.0
+    def verify_izokatu_cipher!
+      raise 'ERROR: Unknown cipher!' if unknown_cipher?
+      raise 'ERROR: Wrap ciphers are not supported!' if wrap_cipher?
+    end
+
+    Contract None => Bool
+    # Verifying cipher is not from OpenSSL private key ciphers or EC ciphers
+    #
+    # @return [Bool] result of verifying cipher is not from OpenSSL private key ciphers of EC ciphers
+    #
+    # @since 0.1.0
+    def unknown_cipher?
+      !Openssl::PKEY_CIPHERS.include?(cipher) && !Openssl::PBKEY_EC_CIPHERS.include?(cipher)
+    end
+
+    Contract None => Bool
+    # Verifying cipher is using WRAP mode
+    #
+    # @return [Bool] result of verifying cipher is using WRAP mode
+    #
+    # @since 0.1.0
+    def wrap_cipher?
+      cipher.include?('wrap') || cipher.include?('WRAP')
+    end
+
+    Contract None => Class
+    # Changing exporter options value from alias of exporter class to exporter class
+    #
+    # @return [Class] exporter class
+    #
+    # @since 0.1.0
+    def select_exporter_class!
+      options[:exporter] = EXPORTER_MAPPING[exporter]
+      @exporter = options[:exporter]
+    end
+
+    Contract None => Class
+    # Changing importer options value from alias of importer class to importer class
+    #
+    # @return [Class] importer class
+    #
+    # @since 0.1.0
+    def select_importer_class!
+      options[:importer] = IMPORTER_MAPPING[importer]
+      @importer = options[:importer]
+    end
+
+    Contract None => Contracts::HashOf[Symbol, Any]
+    # Importing encrypted data, selecting action class with options to call, exporting result of call
+    #
+    # @return [Hash] Encrypted/decrypted data with params or public/private keys
+    #
+    # @since 0.1.0
+    def process_izokatu_options!
+      import_encrypted!(options: options, decode: true) if action == :decryption
+      action_class = select_action
+      action_options = select_action_options(action_class)
+      data, params = action_class.call(**action_options)
+      izokatu_export(data: data, params: params, encode: true)
+    end
+
+    # Izokatu export function
+    #
+    # @param data [Hash] encrypted/decrypted data for export
+    # @param params [Hash] decrypter params for export
+    #
+    # @return [Hash] result of action class call
+    #
+    # @since 0.1.0
+    def izokatu_export(data:, params:, encode:)
+      # WTF: Somehow, even Contract Any => Any for this method is violated
+      case action
+      when :encryption
+        export_encrypted!(encrypted_data: data, decrypter_params: params || {}, encode: encode)
+      when :decryption
+        export_decrypted!(decrypted_data: data, encode: false)
+      else
+        data
+      end
+    end
+
+    Contract None => Class
+    # Selecting action class to be called, based on options
+    #
+    # @return [Class] action class
+    #
+    # @since 0.1.0
+    def select_action
+      ActionCallSelector.call(
+        via: via,
+        mode: mode,
+        action: action,
+        asym_cipher_type: asym_cipher_type,
+        ccm_cipher: ccm_cipher?,
+        auth_cipher: cipher_authenticated?
+      )
+    end
+
+    Contract Class => Contracts::HashOf[Symbol, Any]
+    # Selecting options for action class, based on action class
+    #
+    # @param action_class [Class] selected action class
+    #
+    # @return [Hash] options for action class
+    #
+    # @since 0.1.0
+    def select_action_options(action_class)
+      ActionCallOptionsSelector.call(action_class: action_class, options: options)
+    end
+
+    Contract None => Bool
+    # Verifying cipher mode is equal to CCM
+    #
+    # @return [Bool] result of verifying cipher mode is equal to CCM
+    #
+    # @since 0.1.0
+    def ccm_cipher?
+      cipher.include?('CCM')
+    end
+
+    Contract None => Bool
+    # Verifying cipher as authenticated.
+    # If cipher is authenticated, authenticated tag will be computed from encrypted data.
+    # @note passing EC ciphers as authenticated. Those ciphers used only for key generation
+    #
+    # @return [Bool] result of verifying cipher as authenticated
+    #
+    # @since 0.1.0
+    def cipher_authenticated?
+      return true if Openssl::PBKEY_EC_CIPHERS.include?(cipher)
+
+      OpenSSL::Cipher.new(cipher).encrypt.authenticated? && openssl_auth_exception?
+    end
+
+    Contract None => Bool
+    # Verifying cipher is not using CBC mode or equal to RC4-HMAC-MD5.
+    # These conditions specifying ciphers which passing authenticated? check from OpenSSL, but are not authenticated.
+    #
+    # @return [Bool] result of verifying cipher as OpenSSL exceptions from authenticated? check
+    #
+    # @since 0.1.0
+    def openssl_auth_exception?
+      # In tests of openssl gem, I don't saw assigment of auth_tag or auth_data for cbc ciphers, only padding
+      # (https://github.com/ruby/openssl/blob/master/test/openssl/test_cipher.rb)
+      # Get this error:
+      # OpenSSL::Cipher::CipherError: retrieving the authentication tag failed: ctrl operation not implemented
+      # If not assigning authentication tag, get this error:
+      # ':in `iv_len=': cipher does not support AEAD (OpenSSL::Cipher::CipherError)'
+      !cipher.include?('CBC') && cipher != 'RC4-HMAC-MD5'
+    end
+  end
+end

data/lib/izokatu/action_call_options_selector.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module Izokatu
+  # Izokatu selector of options for selected action class
+  class ActionCallOptionsSelector
+    extend Callable
+
+    include Contracts
+
+    # @return [Class] selected action class
+    attr_reader :action_class
+    # @return [Symbol] action to execute
+    attr_reader :action
+    # @return [Symbol] library used for encryption/decryption
+    attr_reader :via
+    # @return [String] OpenSSL private key cipher
+    # @note also used for OpenSSL public key ec key generation
+    attr_reader :cipher
+    # @return [String] string of clear data for encryption
+    attr_reader :clear_data_string
+    # @return [String] string of encrypted data for decryption
+    attr_reader :encrypted_data_string
+    # @return [RBNACL_KEY_CLASSES || OPENSSL_KEY_CLASSES] public key for public key encryption/decryption
+    attr_reader :public_key
+    # @return [RBNACL_KEY_CLASSES || OPENSSL_KEY_CLASSES] private key for public key encryption/decryption
+    attr_reader :private_key
+    # @return [String] encryption key for private key encryption/decryption
+    attr_reader :key
+    # @return [String] initialization vector for one-time use
+    attr_reader :nonce
+    # @return [String] authenticated data
+    attr_reader :auth_data
+    # @return [String] authentication tag
+    attr_reader :auth_tag
+    # @return [Hash] options for OpenSSL public key EC encryption/decryption
+    attr_reader :ecies_options
+    # @return [Integer] bit number for OpenSSL public key RSA encryption/decryption
+    attr_reader :bit_number
+
+    # RbNaCl public key classes, used for contracts
+    RBNACL_KEY_CLASSES = [
+      RbNaCl::Boxes::Curve25519XSalsa20Poly1305::PrivateKey,
+      RbNaCl::Boxes::Curve25519XSalsa20Poly1305::PublicKey
+    ].freeze
+
+    # OpenSSL public key classes, used for contracts
+    OPENSSL_KEY_CLASSES = [
+      OpenSSL::PKey::RSA,
+      OpenSSL::PKey::EC
+    ].freeze
+
+    Contract Contracts::HashOf[Symbol, Or[Class, Contracts::HashOf[Symbol, Any]]] => Any
+    # Initializing options for action class
+    #
+    # @param action_class (#action_class)
+    # @param options (#options)
+    #
+    # @since 0.1.0
+    def initialize(action_class:, options:)
+      @action_class = action_class.to_s
+      @action = options[:action]
+      @via = options[:via]
+      @cipher = options[:cipher]
+      @clear_data_string = options[:clear_data_string]
+      @encrypted_data_string = options[:encrypted_data_string]
+      @public_key = options[:public_key]
+      @private_key = options[:private_key]
+      @key = options[:key]
+      @nonce = options[:nonce]
+      @auth_data = options[:auth_data]
+      @auth_tag = options[:auth_tag]
+      @ecies_options = options[:ecies_options]
+      @bit_number = options[:bit_number]
+    end
+
+    Contract None => Contracts::HashOf[Symbol, Any]
+    # Selecting options for keys generation class or for encryption/decryption class
+    #
+    # @return [Hash] options for action class call
+    #
+    # @since 0.1.0
+    def perform
+      action == :keys_generation ? select_keys_generation_action_options : select_default_action_options
+    end
+
+    private
+
+    Contract None => Or[{}, Contracts::HashOf[Symbol, Or[String, Pos]]]
+    # Selecting options for keys generation class
+    #
+    # @return [Hash] options for keys generation class
+    #
+    # @since 0.1.0
+    def select_keys_generation_action_options
+      case action_class
+      when 'Izokatu::Rbnacl::PublicKey::KeysGenerator'
+        {}
+      when 'Izokatu::Openssl::PublicKey::RSA::KeysGenerator'
+        { bit_number: bit_number }
+      when 'Izokatu::Openssl::PublicKey::EC::KeysGenerator'
+        { cipher: cipher }
+      end
+    end
+
+    Contract None => Contracts::HashOf[Symbol, Or[*RBNACL_KEY_CLASSES, *OPENSSL_KEY_CLASSES, String, nil]]
+    # Selecting options for encryption/decryption class
+    #
+    # @return [Hash] options for encryption/decryption class
+    #
+    # @since 0.1.0
+    def select_default_action_options
+      via == :rbnacl ? select_rbnacl_action_options : select_openssl_action_options
+    end
+
+    Contract None => Contracts::HashOf[Symbol, Or[*RBNACL_KEY_CLASSES, String, nil]]
+    # Selecting options for Rbnacl encryption/decryption class
+    #
+    # @return [Hash] options for Rbnacl encryption/decryption class
+    #
+    # @since 0.1.0
+    def select_rbnacl_action_options
+      case action_class
+      when 'Izokatu::Rbnacl::PrivateKey::Encrypter'
+        { auth_data: auth_data, clear_data: clear_data_string }
+      when 'Izokatu::Rbnacl::PrivateKey::Decrypter'
+        {
+          encrypted_data: encrypted_data_string,
+          nonce: nonce,
+          key: key,
+          auth_data: auth_data
+        }
+      when 'Izokatu::Rbnacl::PublicKey::Encrypter'
+        {
+          public_key: public_key,
+          private_key: private_key,
+          clear_data: clear_data_string
+        }
+      when 'Izokatu::Rbnacl::PublicKey::Decrypter'
+        {
+          encrypted_data: encrypted_data_string,
+          nonce: nonce,
+          public_key: public_key,
+          private_key: private_key
+        }
+      end
+    end
+
+    Contract None => Contracts::HashOf[Symbol, Or[*OPENSSL_KEY_CLASSES, String, nil]]
+    # Selecting options for Openssl encryption/decryption class
+    #
+    # @return [Hash] options for Openssl encryption/decryption class
+    #
+    # @since 0.1.0
+    def select_openssl_action_options
+      case action_class
+      when 'Izokatu::Openssl::PrivateKey::Default::Encrypter'
+        { cipher: cipher, clear_data: clear_data_string }
+      when 'Izokatu::Openssl::PrivateKey::Default::Decrypter'
+        {
+          cipher: cipher,
+          encrypted_data: encrypted_data_string,
+          key: key,
+          nonce: nonce
+        }
+      when 'Izokatu::Openssl::PrivateKey::Auth::Encrypter'
+        {
+          cipher: cipher,
+          clear_data: clear_data_string,
+          auth_data: auth_data
+        }
+      when 'Izokatu::Openssl::PrivateKey::Auth::Decrypter'
+        {
+          cipher: cipher,
+          encrypted_data: encrypted_data_string,
+          key: key,
+          nonce: nonce,
+          auth_data: auth_data,
+          auth_tag: auth_tag
+        }
+      when 'Izokatu::Openssl::PrivateKey::Auth::CCM::Encrypter'
+        {
+          cipher: cipher,
+          clear_data: clear_data_string,
+          auth_data: auth_data
+        }
+      when 'Izokatu::Openssl::PrivateKey::Auth::CCM::Decrypter'
+        {
+          cipher: cipher,
+          encrypted_data: encrypted_data_string,
+          key: key,
+          nonce: nonce,
+          auth_data: auth_data,
+          auth_tag: auth_tag
+        }
+      when 'Izokatu::Openssl::PublicKey::RSA::Encrypter'
+        { clear_data: clear_data_string, public_key: public_key }
+      when 'Izokatu::Openssl::PublicKey::RSA::Decrypter'
+        { private_key: private_key, encrypted_data: encrypted_data_string }
+      when 'Izokatu::Openssl::PublicKey::EC::Encrypter'
+        {
+          clear_data: clear_data_string,
+          public_key: public_key,
+          ecies_options: ecies_options
+        }
+      when 'Izokatu::Openssl::PublicKey::EC::Decrypter'
+        {
+          private_key: private_key,
+          encrypted_data: encrypted_data_string,
+          ecies_options: ecies_options
+        }
+      end
+    end
+  end
+end