omg-activerecord 8.0.0.alpha1

data/lib/active_record/encryption/envelope_encryption_key_provider.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    # Implements a simple envelope encryption approach where:
+    #
+    # * It generates a random data-encryption key for each encryption operation.
+    # * It stores the generated key along with the encrypted payload. It encrypts this key
+    #   with the master key provided in the +active_record_encryption.primary_key+ credential.
+    #
+    # This provider can work with multiple master keys. It will use the last one for encrypting.
+    #
+    # When +config.active_record.encryption.store_key_references+ is true, it will also store a reference to
+    # the specific master key that was used to encrypt the data-encryption key. When not set,
+    # it will try all the configured master keys looking for the right one, in order to
+    # return the right decryption key.
+    class EnvelopeEncryptionKeyProvider
+      def encryption_key
+        random_secret = generate_random_secret
+        ActiveRecord::Encryption::Key.new(random_secret).tap do |key|
+          key.public_tags.encrypted_data_key = encrypt_data_key(random_secret)
+          key.public_tags.encrypted_data_key_id = active_primary_key.id if ActiveRecord::Encryption.config.store_key_references
+        end
+      end
+
+      def decryption_keys(encrypted_message)
+        secret = decrypt_data_key(encrypted_message)
+        secret ? [ActiveRecord::Encryption::Key.new(secret)] : []
+      end
+
+      def active_primary_key
+        @active_primary_key ||= primary_key_provider.encryption_key
+      end
+
+      private
+        def encrypt_data_key(random_secret)
+          ActiveRecord::Encryption.cipher.encrypt(random_secret, key: active_primary_key.secret)
+        end
+
+        def decrypt_data_key(encrypted_message)
+          encrypted_data_key = encrypted_message.headers.encrypted_data_key
+          key = primary_key_provider.decryption_keys(encrypted_message)&.collect(&:secret)
+          ActiveRecord::Encryption.cipher.decrypt encrypted_data_key, key: key if key
+        end
+
+        def primary_key_provider
+          @primary_key_provider ||= DerivedSecretKeyProvider.new(ActiveRecord::Encryption.config.primary_key)
+        end
+
+        def generate_random_secret
+          ActiveRecord::Encryption.key_generator.generate_random_key
+        end
+    end
+  end
+end

data/lib/active_record/encryption/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    module Errors
+      class Base < StandardError; end
+      class Encoding < Base; end
+      class Decryption < Base; end
+      class Encryption < Base; end
+      class Configuration < Base; end
+      class ForbiddenClass < Base; end
+      class EncryptedContentIntegrity < Base; end
+    end
+  end
+end

data/lib/active_record/encryption/extended_deterministic_queries.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    # Automatically expand encrypted arguments to support querying both encrypted and unencrypted data
+    #
+    # Active Record \Encryption supports querying the db using deterministic attributes. For example:
+    #
+    #   Contact.find_by(email_address: "jorge@hey.com")
+    #
+    # The value "jorge@hey.com" will get encrypted automatically to perform the query. But there is
+    # a problem while the data is being encrypted. This won't work. During that time, you need these
+    # queries to be:
+    #
+    #   Contact.find_by(email_address: [ "jorge@hey.com", "<encrypted jorge@hey.com>" ])
+    #
+    # This patches ActiveRecord to support this automatically. It addresses both:
+    #
+    # * ActiveRecord::Base - Used in <tt>Contact.find_by_email_address(...)</tt>
+    # * ActiveRecord::Relation - Used in <tt>Contact.internal.find_by_email_address(...)</tt>
+    #
+    # This module is included if `config.active_record.encryption.extend_queries` is `true`.
+    module ExtendedDeterministicQueries
+      def self.install_support
+        # ActiveRecord::Base relies on ActiveRecord::Relation (ActiveRecord::QueryMethods) but it does
+        # some prepared statements caching. That's why we need to intercept +ActiveRecord::Base+ as soon
+        # as it's invoked (so that the proper prepared statement is cached).
+        ActiveRecord::Relation.prepend(RelationQueries)
+        ActiveRecord::Base.include(CoreQueries)
+        ActiveRecord::Encryption::EncryptedAttributeType.prepend(ExtendedEncryptableType)
+      end
+
+      # When modifying this file run performance tests in
+      # +activerecord/test/cases/encryption/performance/extended_deterministic_queries_performance_test.rb+
+      # to make sure performance overhead is acceptable.
+      #
+      # @TODO We will extend this to support previous "encryption context" versions in future iterations
+      # @TODO Experimental. Support for every kind of query is pending
+      # @TODO It should not patch anything if not needed (no previous schemes or no support for previous encryption schemes)
+
+      module EncryptedQuery # :nodoc:
+        class << self
+          def process_arguments(owner, args, check_for_additional_values)
+            owner = owner.model if owner.is_a?(Relation)
+
+            return args if owner.deterministic_encrypted_attributes&.empty?
+
+            if args.is_a?(Array) && (options = args.first).is_a?(Hash)
+              options = options.transform_keys do |key|
+                if key.is_a?(Array)
+                  key.map(&:to_s)
+                else
+                  key.to_s
+                end
+              end
+              args[0] = options
+
+              owner.deterministic_encrypted_attributes&.each do |attribute_name|
+                attribute_name = attribute_name.to_s
+                type = owner.type_for_attribute(attribute_name)
+                if !type.previous_types.empty? && value = options[attribute_name]
+                  options[attribute_name] = process_encrypted_query_argument(value, check_for_additional_values, type)
+                end
+              end
+            end
+
+            args
+          end
+
+          private
+            def process_encrypted_query_argument(value, check_for_additional_values, type)
+              return value if check_for_additional_values && value.is_a?(Array) && value.last.is_a?(AdditionalValue)
+
+              case value
+              when String, Array
+                list = Array(value)
+                list + list.flat_map do |each_value|
+                  if check_for_additional_values && each_value.is_a?(AdditionalValue)
+                    each_value
+                  else
+                    additional_values_for(each_value, type)
+                  end
+                end
+              else
+                value
+              end
+            end
+
+            def additional_values_for(value, type)
+              type.previous_types.collect do |additional_type|
+                AdditionalValue.new(value, additional_type)
+              end
+            end
+        end
+      end
+
+      module RelationQueries
+        def where(*args)
+          super(*EncryptedQuery.process_arguments(self, args, true))
+        end
+
+        def exists?(*args)
+          super(*EncryptedQuery.process_arguments(self, args, true))
+        end
+
+        def scope_for_create
+          return super unless model.deterministic_encrypted_attributes&.any?
+
+          scope_attributes = super
+          wheres = where_values_hash
+
+          model.deterministic_encrypted_attributes.each do |attribute_name|
+            attribute_name = attribute_name.to_s
+            values = wheres[attribute_name]
+            if values.is_a?(Array) && values[1..].all?(AdditionalValue)
+              scope_attributes[attribute_name] = values.first
+            end
+          end
+
+          scope_attributes
+        end
+      end
+
+      module CoreQueries
+        extend ActiveSupport::Concern
+
+        class_methods do
+          def find_by(*args)
+            super(*EncryptedQuery.process_arguments(self, args, false))
+          end
+        end
+      end
+
+      class AdditionalValue
+        attr_reader :value, :type
+
+        def initialize(value, type)
+          @type = type
+          @value = process(value)
+        end
+
+        private
+          def process(value)
+            type.serialize(value)
+          end
+      end
+
+      module ExtendedEncryptableType
+        def serialize(data)
+          if data.is_a?(AdditionalValue)
+            data.value
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/encryption/extended_deterministic_uniqueness_validator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    module ExtendedDeterministicUniquenessValidator
+      def self.install_support
+        ActiveRecord::Validations::UniquenessValidator.prepend(EncryptedUniquenessValidator)
+      end
+
+      module EncryptedUniquenessValidator
+        def validate_each(record, attribute, value)
+          super(record, attribute, value)
+
+          klass = record.class
+          if klass.deterministic_encrypted_attributes&.include?(attribute)
+            encrypted_type = klass.type_for_attribute(attribute)
+            encrypted_type.previous_types.each do |type|
+              encrypted_value = type.serialize(value)
+              ActiveRecord::Encryption.without_encryption do
+                super(record, attribute, encrypted_value)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/encryption/key.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    # A key is a container for a given +secret+
+    #
+    # Optionally, it can include +public_tags+. These tags are meant to be stored
+    # in clean (public) and can be used, for example, to include information that
+    # references the key for a future retrieval operation.
+    class Key
+      attr_reader :secret, :public_tags
+
+      def initialize(secret)
+        @secret = secret
+        @public_tags = Properties.new
+      end
+
+      def self.derive_from(password)
+        secret = ActiveRecord::Encryption.key_generator.derive_key_from(password)
+        ActiveRecord::Encryption::Key.new(secret)
+      end
+
+      def id
+        Digest::SHA1.hexdigest(secret).first(4)
+      end
+    end
+  end
+end

data/lib/active_record/encryption/key_generator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module ActiveRecord
+  module Encryption
+    # Utility for generating and deriving random keys.
+    class KeyGenerator
+      attr_reader :hash_digest_class
+
+      def initialize(hash_digest_class: ActiveRecord::Encryption.config.hash_digest_class)
+        @hash_digest_class = hash_digest_class
+      end
+
+      # Returns a random key. The key will have a size in bytes of +:length+ (configured +Cipher+'s length by default)
+      def generate_random_key(length: key_length)
+        SecureRandom.random_bytes(length)
+      end
+
+      # Returns a random key in hexadecimal format. The key will have a size in bytes of +:length+ (configured +Cipher+'s
+      # length by default)
+      #
+      # Hexadecimal format is handy for representing keys as printable text. To maximize the space of characters used, it is
+      # good practice including not printable characters. Hexadecimal format ensures that generated keys are representable with
+      # plain text
+      #
+      # To convert back to the original string with the desired length:
+      #
+      #   [ value ].pack("H*")
+      def generate_random_hex_key(length: key_length)
+        generate_random_key(length: length).unpack("H*")[0]
+      end
+
+      # Derives a key from the given password. The key will have a size in bytes of +:length+ (configured +Cipher+'s length
+      # by default)
+      #
+      # The generated key will be salted with the value of +ActiveRecord::Encryption.key_derivation_salt+
+      def derive_key_from(password, length: key_length)
+        ActiveSupport::KeyGenerator.new(password, hash_digest_class: hash_digest_class)
+          .generate_key(key_derivation_salt, length)
+      end
+
+      private
+        def key_derivation_salt
+          @key_derivation_salt ||= ActiveRecord::Encryption.config.key_derivation_salt
+        end
+
+        def key_length
+          @key_length ||= ActiveRecord::Encryption.cipher.key_length
+        end
+    end
+  end
+end

data/lib/active_record/encryption/key_provider.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    # A +KeyProvider+ serves keys:
+    #
+    # * An encryption key
+    # * A list of potential decryption keys. Serving multiple decryption keys supports rotation-schemes
+    #   where new keys are added but old keys need to continue working
+    class KeyProvider
+      def initialize(keys)
+        @keys = Array(keys)
+      end
+
+      # Returns the last key in the list as the active key to perform encryptions
+      #
+      # When +ActiveRecord::Encryption.config.store_key_references+ is true, the key will include
+      # a public tag referencing the key itself. That key will be stored in the public
+      # headers of the encrypted message
+      def encryption_key
+        @encryption_key ||= @keys.last.tap do |key|
+          key.public_tags.encrypted_data_key_id = key.id if ActiveRecord::Encryption.config.store_key_references
+        end
+
+        @encryption_key
+      end
+
+      # Returns the list of decryption keys
+      #
+      # When the message holds a reference to its encryption key, it will return an array
+      # with that key. If not, it will return the list of keys.
+      def decryption_keys(encrypted_message)
+        if encrypted_message.headers.encrypted_data_key_id
+          keys_grouped_by_id[encrypted_message.headers.encrypted_data_key_id]
+        else
+          @keys
+        end
+      end
+
+      private
+        def keys_grouped_by_id
+          @keys_grouped_by_id ||= @keys.group_by(&:id)
+        end
+    end
+  end
+end

data/lib/active_record/encryption/message.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    # A message defines the structure of the data we store in encrypted attributes. It contains:
+    #
+    # * An encrypted payload
+    # * A list of unencrypted headers
+    #
+    # See Encryptor#encrypt
+    class Message
+      attr_accessor :payload, :headers
+
+      def initialize(payload: nil, headers: {})
+        validate_payload_type(payload)
+
+        @payload = payload
+        @headers = Properties.new(headers)
+      end
+
+      def ==(other_message)
+        payload == other_message.payload && headers == other_message.headers
+      end
+
+      private
+        def validate_payload_type(payload)
+          unless payload.is_a?(String) || payload.nil?
+            raise ActiveRecord::Encryption::Errors::ForbiddenClass, "Only string payloads allowed"
+          end
+        end
+    end
+  end
+end

data/lib/active_record/encryption/message_pack_message_serializer.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "active_support/message_pack"
+
+module ActiveRecord
+  module Encryption
+    # A message serializer that serializes +Messages+ with MessagePack.
+    #
+    # The message is converted to a hash with this structure:
+    #
+    #   {
+    #     p: <payload>,
+    #     h: {
+    #       header1: value1,
+    #       header2: value2,
+    #       ...
+    #     }
+    #   }
+    #
+    # Then it is converted to the MessagePack format.
+    class MessagePackMessageSerializer
+      def dump(message)
+        raise Errors::ForbiddenClass unless message.is_a?(Message)
+        ActiveSupport::MessagePack.dump(message_to_hash(message))
+      end
+
+      def load(serialized_content)
+        data = ActiveSupport::MessagePack.load(serialized_content)
+        hash_to_message(data, 1)
+      rescue RuntimeError
+        raise Errors::Decryption
+      end
+
+      def binary?
+        true
+      end
+
+      private
+        def message_to_hash(message)
+          {
+            "p" => message.payload,
+            "h" => headers_to_hash(message.headers)
+          }
+        end
+
+        def headers_to_hash(headers)
+          headers.transform_values do |value|
+            value.is_a?(Message) ? message_to_hash(value) : value
+          end
+        end
+
+        def hash_to_message(data, level)
+          validate_message_data_format(data, level)
+          Message.new(payload: data["p"], headers: parse_properties(data["h"], level))
+        end
+
+        def validate_message_data_format(data, level)
+          if level > 2
+            raise Errors::Decryption, "More than one level of hash nesting in headers is not supported"
+          end
+
+          unless data.is_a?(Hash) && data.has_key?("p")
+            raise Errors::Decryption, "Invalid data format: hash without payload"
+          end
+        end
+
+        def parse_properties(headers, level)
+          Properties.new.tap do |properties|
+            headers&.each do |key, value|
+              properties[key] = value.is_a?(Hash) ? hash_to_message(value, level + 1) : value
+            end
+          end
+        end
+    end
+  end
+end

data/lib/active_record/encryption/message_serializer.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module ActiveRecord
+  module Encryption
+    # A message serializer that serializes +Messages+ with JSON.
+    #
+    # The generated structure is pretty simple:
+    #
+    #   {
+    #     p: <payload>,
+    #     h: {
+    #       header1: value1,
+    #       header2: value2,
+    #       ...
+    #     }
+    #   }
+    #
+    # Both the payload and the header values are encoded with Base64
+    # to prevent JSON parsing errors and encoding issues when
+    # storing the resulting serialized data.
+    class MessageSerializer
+      def load(serialized_content)
+        data = JSON.parse(serialized_content)
+        parse_message(data, 1)
+      rescue JSON::ParserError
+        raise ActiveRecord::Encryption::Errors::Encoding
+      end
+
+      def dump(message)
+        raise ActiveRecord::Encryption::Errors::ForbiddenClass unless message.is_a?(ActiveRecord::Encryption::Message)
+        JSON.dump message_to_json(message)
+      end
+
+      def binary?
+        false
+      end
+
+      private
+        def parse_message(data, level)
+          validate_message_data_format(data, level)
+          ActiveRecord::Encryption::Message.new(payload: decode_if_needed(data["p"]), headers: parse_properties(data["h"], level))
+        end
+
+        def validate_message_data_format(data, level)
+          if level > 2
+            raise ActiveRecord::Encryption::Errors::Decryption, "More than one level of hash nesting in headers is not supported"
+          end
+
+          unless data.is_a?(Hash) && data.has_key?("p")
+            raise ActiveRecord::Encryption::Errors::Decryption, "Invalid data format: hash without payload"
+          end
+        end
+
+        def parse_properties(headers, level)
+          ActiveRecord::Encryption::Properties.new.tap do |properties|
+            headers&.each do |key, value|
+              properties[key] = value.is_a?(Hash) ? parse_message(value, level + 1) : decode_if_needed(value)
+            end
+          end
+        end
+
+        def message_to_json(message)
+          {
+            p: encode_if_needed(message.payload),
+            h: headers_to_json(message.headers)
+          }
+        end
+
+        def headers_to_json(headers)
+          headers.transform_values do |value|
+            value.is_a?(ActiveRecord::Encryption::Message) ? message_to_json(value) : encode_if_needed(value)
+          end
+        end
+
+        def encode_if_needed(value)
+          if value.is_a?(String)
+            ::Base64.strict_encode64 value
+          else
+            value
+          end
+        end
+
+        def decode_if_needed(value)
+          if value.is_a?(String)
+            ::Base64.strict_decode64(value)
+          else
+            value
+          end
+        rescue ArgumentError, TypeError
+          raise Errors::Encoding
+        end
+    end
+  end
+end

data/lib/active_record/encryption/null_encryptor.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    # An encryptor that won't decrypt or encrypt. It will just return the passed
+    # values
+    class NullEncryptor
+      def encrypt(clean_text, key_provider: nil, cipher_options: {})
+        clean_text
+      end
+
+      def decrypt(encrypted_text, key_provider: nil, cipher_options: {})
+        encrypted_text
+      end
+
+      def encrypted?(text)
+        false
+      end
+
+      def binary?
+        false
+      end
+    end
+  end
+end

data/lib/active_record/encryption/properties.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    # This is a wrapper for a hash of encryption properties. It is used by
+    # +Key+ (public tags) and +Message+ (headers).
+    #
+    # Since properties are serialized in messages, it is important for storage
+    # efficiency to keep their keys as short as possible. It defines accessors
+    # for common properties that will keep these keys very short while exposing
+    # a readable name.
+    #
+    #   message.headers.encrypted_data_key # instead of message.headers[:k]
+    #
+    # See +Properties::DEFAULT_PROPERTIES+, Key, Message
+    class Properties
+      ALLOWED_VALUE_CLASSES = [String, ActiveRecord::Encryption::Message, Numeric, Integer, Float, BigDecimal, TrueClass, FalseClass, Symbol, NilClass]
+
+      delegate_missing_to :data
+      delegate :==, :[], :each, :key?, to: :data
+
+      # For each entry it generates an accessor exposing the full name
+      DEFAULT_PROPERTIES = {
+        encrypted_data_key: "k",
+        encrypted_data_key_id: "i",
+        compressed: "c",
+        iv: "iv",
+        auth_tag: "at",
+        encoding: "e"
+      }
+
+      DEFAULT_PROPERTIES.each do |name, key|
+        define_method name do
+          self[key.to_sym]
+        end
+
+        define_method "#{name}=" do |value|
+          self[key.to_sym] = value
+        end
+      end
+
+      def initialize(initial_properties = {})
+        @data = {}
+        add(initial_properties)
+      end
+
+      # Set a value for a given key
+      #
+      # It will raise an +EncryptedContentIntegrity+ if the value exists
+      def []=(key, value)
+        raise Errors::EncryptedContentIntegrity, "Properties can't be overridden: #{key}" if key?(key)
+        validate_value_type(value)
+        data[key] = value
+      end
+
+      def validate_value_type(value)
+        unless ALLOWED_VALUE_CLASSES.include?(value.class) || ALLOWED_VALUE_CLASSES.any? { |klass| value.is_a?(klass) }
+          raise ActiveRecord::Encryption::Errors::ForbiddenClass, "Can't store a #{value.class}, only properties of type #{ALLOWED_VALUE_CLASSES.inspect} are allowed"
+        end
+      end
+
+      def add(other_properties)
+        other_properties.each do |key, value|
+          self[key.to_sym] = value
+        end
+      end
+
+      def to_h
+        data
+      end
+
+      private
+        attr_reader :data
+    end
+  end
+end