omg-activerecord 8.0.0.alpha1

data/lib/active_record/encryption/encryptable_record.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    # This is the concern mixed in Active Record models to make them encryptable. It adds the +encrypts+
+    # attribute declaration, as well as the API to encrypt and decrypt records.
+    module EncryptableRecord
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :encrypted_attributes
+
+        validate :cant_modify_encrypted_attributes_when_frozen, if: -> { has_encrypted_attributes? && ActiveRecord::Encryption.context.frozen_encryption? }
+      end
+
+      class_methods do
+        # Encrypts the +name+ attribute.
+        #
+        # === Options
+        #
+        # * <tt>:key_provider</tt> - A key provider to provide encryption and decryption keys. Defaults to
+        #   +ActiveRecord::Encryption.key_provider+.
+        # * <tt>:key</tt> - A password to derive the key from. It's a shorthand for a +:key_provider+ that
+        #   serves derivated keys. Both options can't be used at the same time.
+        # * <tt>:deterministic</tt> - By default, encryption is not deterministic. It will use a random
+        #   initialization vector for each encryption operation. This means that encrypting the same content
+        #   with the same key twice will generate different ciphertexts. When set to +true+, it will generate the
+        #   initialization vector based on the encrypted content. This means that the same content will generate
+        #   the same ciphertexts. This enables querying encrypted text with Active Record. Deterministic encryption
+        #   will use the oldest encryption scheme to encrypt new data by default. You can change this by setting
+        #   <tt>deterministic: { fixed: false }</tt>. That will make it use the newest encryption scheme for encrypting new
+        #   data.
+        # * <tt>:support_unencrypted_data</tt> - If `config.active_record.encryption.support_unencrypted_data` is +true+,
+        #   you can set this to +false+ to opt out of unencrypted data support for this attribute. This is useful for
+        #   scenarios where you encrypt one column, and want to disable support for unencrypted data without having to tweak
+        #   the global setting.
+        # * <tt>:downcase</tt> - When true, it converts the encrypted content to downcase automatically. This allows to
+        #   effectively ignore case when querying data. Notice that the case is lost. Use +:ignore_case+ if you are interested
+        #   in preserving it.
+        # * <tt>:ignore_case</tt> - When true, it behaves like +:downcase+ but, it also preserves the original case in a specially
+        #   designated column +original_<name>+. When reading the encrypted content, the version with the original case is
+        #   served. But you can still execute queries that will ignore the case. This option can only be used when +:deterministic+
+        #   is true.
+        # * <tt>:context_properties</tt> - Additional properties that will override +Context+ settings when this attribute is
+        #   encrypted and decrypted. E.g: +encryptor:+, +cipher:+, +message_serializer:+, etc.
+        # * <tt>:previous</tt> - List of previous encryption schemes. When provided, they will be used in order when trying to read
+        #   the attribute. Each entry of the list can contain the properties supported by #encrypts. Also, when deterministic
+        #   encryption is used, they will be used to generate additional ciphertexts to check in the queries.
+        def encrypts(*names, key_provider: nil, key: nil, deterministic: false, support_unencrypted_data: nil, downcase: false, ignore_case: false, previous: [], compress: true, compressor: nil, **context_properties)
+          self.encrypted_attributes ||= Set.new # not using :default because the instance would be shared across classes
+
+          names.each do |name|
+            encrypt_attribute name, key_provider: key_provider, key: key, deterministic: deterministic, support_unencrypted_data: support_unencrypted_data, downcase: downcase, ignore_case: ignore_case, previous: previous, compress: compress, compressor: compressor, **context_properties
+          end
+        end
+
+        # Returns the list of deterministic encryptable attributes in the model class.
+        def deterministic_encrypted_attributes
+          @deterministic_encrypted_attributes ||= encrypted_attributes&.find_all do |attribute_name|
+            type_for_attribute(attribute_name).deterministic?
+          end
+        end
+
+        # Given a attribute name, it returns the name of the source attribute when it's a preserved one.
+        def source_attribute_from_preserved_attribute(attribute_name)
+          attribute_name.to_s.sub(ORIGINAL_ATTRIBUTE_PREFIX, "") if attribute_name.start_with?(ORIGINAL_ATTRIBUTE_PREFIX)
+        end
+
+        private
+          def scheme_for(key_provider: nil, key: nil, deterministic: false, support_unencrypted_data: nil, downcase: false, ignore_case: false, previous: [], **context_properties)
+            ActiveRecord::Encryption::Scheme.new(key_provider: key_provider, key: key, deterministic: deterministic,
+              support_unencrypted_data: support_unencrypted_data, downcase: downcase, ignore_case: ignore_case, **context_properties).tap do |scheme|
+              scheme.previous_schemes = global_previous_schemes_for(scheme) +
+              Array.wrap(previous).collect { |scheme_config| ActiveRecord::Encryption::Scheme.new(**scheme_config) }
+            end
+          end
+
+          def global_previous_schemes_for(scheme)
+            ActiveRecord::Encryption.config.previous_schemes.filter_map do |previous_scheme|
+              scheme.merge(previous_scheme) if scheme.compatible_with?(previous_scheme)
+            end
+          end
+
+          def encrypt_attribute(name, key_provider: nil, key: nil, deterministic: false, support_unencrypted_data: nil, downcase: false, ignore_case: false, previous: [], compress: true, compressor: nil, **context_properties)
+            encrypted_attributes << name.to_sym
+
+            decorate_attributes([name]) do |name, cast_type|
+              scheme = scheme_for key_provider: key_provider, key: key, deterministic: deterministic, support_unencrypted_data: support_unencrypted_data, \
+                downcase: downcase, ignore_case: ignore_case, previous: previous, compress: compress, compressor: compressor, **context_properties
+
+              ActiveRecord::Encryption::EncryptedAttributeType.new(scheme: scheme, cast_type: cast_type, default: columns_hash[name.to_s]&.default)
+            end
+
+            preserve_original_encrypted(name) if ignore_case
+            ActiveRecord::Encryption.encrypted_attribute_was_declared(self, name)
+          end
+
+          def preserve_original_encrypted(name)
+            original_attribute_name = "#{ORIGINAL_ATTRIBUTE_PREFIX}#{name}".to_sym
+
+            if !ActiveRecord::Encryption.config.support_unencrypted_data && !column_names.include?(original_attribute_name.to_s)
+              raise Errors::Configuration, "To use :ignore_case for '#{name}' you must create an additional column named '#{original_attribute_name}'"
+            end
+
+            encrypts original_attribute_name
+            override_accessors_to_preserve_original name, original_attribute_name
+          end
+
+          def override_accessors_to_preserve_original(name, original_attribute_name)
+            include(Module.new do
+              define_method name do
+                if ((value = super()) && encrypted_attribute?(name)) || !ActiveRecord::Encryption.config.support_unencrypted_data
+                  send(original_attribute_name)
+                else
+                  value
+                end
+              end
+
+              define_method "#{name}=" do |value|
+                self.send "#{original_attribute_name}=", value
+                super(value)
+              end
+            end)
+          end
+
+          def load_schema! # :nodoc:
+            super
+
+            add_length_validation_for_encrypted_columns if ActiveRecord::Encryption.config.validate_column_size
+          end
+
+          def add_length_validation_for_encrypted_columns
+            encrypted_attributes&.each do |attribute_name|
+              validate_column_size attribute_name
+            end
+          end
+
+          def validate_column_size(attribute_name)
+            if limit = columns_hash[attribute_name.to_s]&.limit
+              validates_length_of attribute_name, maximum: limit
+            end
+          end
+      end
+
+      # Returns whether a given attribute is encrypted or not.
+      def encrypted_attribute?(attribute_name)
+        name = attribute_name.to_s
+        name = self.class.attribute_aliases[name] || name
+
+        return false unless self.class.encrypted_attributes&.include? name.to_sym
+
+        type = type_for_attribute(name)
+        type.encrypted? read_attribute_before_type_cast(name)
+      end
+
+      # Returns the ciphertext for +attribute_name+.
+      def ciphertext_for(attribute_name)
+        if encrypted_attribute?(attribute_name)
+          read_attribute_before_type_cast(attribute_name)
+        else
+          read_attribute_for_database(attribute_name)
+        end
+      end
+
+      # Encrypts all the encryptable attributes and saves the changes.
+      def encrypt
+        encrypt_attributes if has_encrypted_attributes?
+      end
+
+      # Decrypts all the encryptable attributes and saves the changes.
+      def decrypt
+        decrypt_attributes if has_encrypted_attributes?
+      end
+
+      private
+        ORIGINAL_ATTRIBUTE_PREFIX = "original_"
+
+        def _create_record(attribute_names = self.attribute_names)
+          if has_encrypted_attributes?
+            # Always persist encrypted attributes, because an attribute might be
+            # encrypting a column default value.
+            attribute_names |= self.class.encrypted_attributes.map(&:to_s)
+          end
+          super
+        end
+
+        def encrypt_attributes
+          validate_encryption_allowed
+
+          update_columns build_encrypt_attribute_assignments
+        end
+
+        def decrypt_attributes
+          validate_encryption_allowed
+
+          decrypt_attribute_assignments = build_decrypt_attribute_assignments
+          ActiveRecord::Encryption.without_encryption { update_columns decrypt_attribute_assignments }
+        end
+
+        def validate_encryption_allowed
+          raise ActiveRecord::Encryption::Errors::Configuration, "can't be modified because it is encrypted" if ActiveRecord::Encryption.context.frozen_encryption?
+        end
+
+        def has_encrypted_attributes?
+          self.class.encrypted_attributes.present?
+        end
+
+        def build_encrypt_attribute_assignments
+          Array(self.class.encrypted_attributes).index_with do |attribute_name|
+            self[attribute_name]
+          end
+        end
+
+        def build_decrypt_attribute_assignments
+          Array(self.class.encrypted_attributes).to_h do |attribute_name|
+            type = type_for_attribute(attribute_name)
+            encrypted_value = ciphertext_for(attribute_name)
+            new_value = type.deserialize(encrypted_value)
+            [attribute_name, new_value]
+          end
+        end
+
+        def cant_modify_encrypted_attributes_when_frozen
+          self.class.encrypted_attributes.each do |attribute|
+            errors.add(attribute.to_sym, "can't be modified because it is encrypted") if changed_attributes.include?(attribute)
+          end
+        end
+    end
+  end
+end

data/lib/active_record/encryption/encrypted_attribute_type.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    # An ActiveModel::Type::Value that encrypts/decrypts strings of text.
+    #
+    # This is the central piece that connects the encryption system with +encrypts+ declarations in the
+    # model classes. Whenever you declare an attribute as encrypted, it configures an +EncryptedAttributeType+
+    # for that attribute.
+    class EncryptedAttributeType < ::ActiveModel::Type::Value
+      include ActiveModel::Type::Helpers::Mutable
+
+      attr_reader :scheme, :cast_type
+
+      delegate :key_provider, :downcase?, :deterministic?, :previous_schemes, :with_context, :fixed?, to: :scheme
+      delegate :accessor, :type, to: :cast_type
+
+      # === Options
+      #
+      # * <tt>:scheme</tt> - A +Scheme+ with the encryption properties for this attribute.
+      # * <tt>:cast_type</tt> - A type that will be used to serialize (before encrypting) and deserialize
+      #   (after decrypting). ActiveModel::Type::String by default.
+      def initialize(scheme:, cast_type: ActiveModel::Type::String.new, previous_type: false, default: nil)
+        super()
+        @scheme = scheme
+        @cast_type = cast_type
+        @previous_type = previous_type
+        @default = default
+      end
+
+      def cast(value)
+        cast_type.cast(value)
+      end
+
+      def deserialize(value)
+        cast_type.deserialize decrypt(value)
+      end
+
+      def serialize(value)
+        if serialize_with_oldest?
+          serialize_with_oldest(value)
+        else
+          serialize_with_current(value)
+        end
+      end
+
+      def encrypted?(value)
+        with_context { encryptor.encrypted? value }
+      end
+
+      def changed_in_place?(raw_old_value, new_value)
+        old_value = raw_old_value.nil? ? nil : deserialize(raw_old_value)
+        old_value != new_value
+      end
+
+      def previous_types # :nodoc:
+        @previous_types ||= {} # Memoizing on support_unencrypted_data so that we can tweak it during tests
+        @previous_types[support_unencrypted_data?] ||= build_previous_types_for(previous_schemes_including_clean_text)
+      end
+
+      def support_unencrypted_data?
+        ActiveRecord::Encryption.config.support_unencrypted_data && scheme.support_unencrypted_data? && !previous_type?
+      end
+
+      private
+        def previous_schemes_including_clean_text
+          previous_schemes.including((clean_text_scheme if support_unencrypted_data?)).compact
+        end
+
+        def previous_types_without_clean_text
+          @previous_types_without_clean_text ||= build_previous_types_for(previous_schemes)
+        end
+
+        def build_previous_types_for(schemes)
+          schemes.collect do |scheme|
+            EncryptedAttributeType.new(scheme: scheme, previous_type: true)
+          end
+        end
+
+        def previous_type?
+          @previous_type
+        end
+
+        def decrypt_as_text(value)
+          with_context do
+            unless value.nil?
+              if @default && @default == value
+                value
+              else
+                encryptor.decrypt(value, **decryption_options)
+              end
+            end
+          end
+        rescue ActiveRecord::Encryption::Errors::Base => error
+          if previous_types_without_clean_text.blank?
+            handle_deserialize_error(error, value)
+          else
+            try_to_deserialize_with_previous_encrypted_types(value)
+          end
+        end
+
+        def decrypt(value)
+          text_to_database_type decrypt_as_text(database_type_to_text(value))
+        end
+
+        def try_to_deserialize_with_previous_encrypted_types(value)
+          previous_types.each.with_index do |type, index|
+            break type.deserialize(value)
+          rescue ActiveRecord::Encryption::Errors::Base => error
+            handle_deserialize_error(error, value) if index == previous_types.length - 1
+          end
+        end
+
+        def handle_deserialize_error(error, value)
+          if error.is_a?(Errors::Decryption) && support_unencrypted_data?
+            value
+          else
+            raise error
+          end
+        end
+
+        def serialize_with_oldest?
+          @serialize_with_oldest ||= fixed? && previous_types_without_clean_text.present?
+        end
+
+        def serialize_with_oldest(value)
+          previous_types.first.serialize(value)
+        end
+
+        def serialize_with_current(value)
+          casted_value = cast_type.serialize(value)
+          casted_value = casted_value&.downcase if downcase?
+          encrypt(casted_value.to_s) unless casted_value.nil?
+        end
+
+        def encrypt_as_text(value)
+          with_context do
+            if encryptor.binary? && !cast_type.binary?
+              raise Errors::Encoding, "Binary encoded data can only be stored in binary columns"
+            end
+
+            encryptor.encrypt(value, **encryption_options)
+          end
+        end
+
+        def encrypt(value)
+          text_to_database_type encrypt_as_text(value)
+        end
+
+        def encryptor
+          ActiveRecord::Encryption.encryptor
+        end
+
+        def encryption_options
+          { key_provider: key_provider, cipher_options: { deterministic: deterministic? } }.compact
+        end
+
+        def decryption_options
+          { key_provider: key_provider }.compact
+        end
+
+        def clean_text_scheme
+          @clean_text_scheme ||= ActiveRecord::Encryption::Scheme.new(downcase: downcase?, encryptor: ActiveRecord::Encryption::NullEncryptor.new)
+        end
+
+        def text_to_database_type(value)
+          if value && cast_type.binary?
+            ActiveModel::Type::Binary::Data.new(value)
+          else
+            value
+          end
+        end
+
+        def database_type_to_text(value)
+          if value && cast_type.binary?
+            binary_cast_type = cast_type.serialized? ? cast_type.subtype : cast_type
+            binary_cast_type.deserialize(value)
+          else
+            value
+          end
+        end
+    end
+  end
+end

data/lib/active_record/encryption/encrypted_fixtures.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    module EncryptedFixtures
+      def initialize(fixture, model_class)
+        @clean_values = {}
+        encrypt_fixture_data(fixture, model_class)
+        process_preserved_original_columns(fixture, model_class)
+        super
+      end
+
+      private
+        def encrypt_fixture_data(fixture, model_class)
+          model_class&.encrypted_attributes&.each do |attribute_name|
+            if clean_value = fixture[attribute_name.to_s]
+              @clean_values[attribute_name.to_s] = clean_value
+
+              type = model_class.type_for_attribute(attribute_name)
+              encrypted_value = type.serialize(clean_value)
+              fixture[attribute_name.to_s] = encrypted_value
+            end
+          end
+        end
+
+        def process_preserved_original_columns(fixture, model_class)
+          model_class&.encrypted_attributes&.each do |attribute_name|
+            if source_attribute_name = model_class.source_attribute_from_preserved_attribute(attribute_name)
+              clean_value = @clean_values[source_attribute_name.to_s]
+              type = model_class.type_for_attribute(attribute_name)
+              encrypted_value = type.serialize(clean_value)
+              fixture[attribute_name.to_s] = encrypted_value
+            end
+          end
+        end
+    end
+  end
+end

data/lib/active_record/encryption/encrypting_only_encryptor.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    # An encryptor that can encrypt data but can't decrypt it.
+    class EncryptingOnlyEncryptor < Encryptor
+      def decrypt(encrypted_text, key_provider: nil, cipher_options: {})
+        encrypted_text
+      end
+    end
+  end
+end

data/lib/active_record/encryption/encryptor.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "active_support/core_ext/numeric"
+
+module ActiveRecord
+  module Encryption
+    # An encryptor exposes the encryption API that ActiveRecord::Encryption::EncryptedAttributeType
+    # uses for encrypting and decrypting attribute values.
+    #
+    # It interacts with a KeyProvider for getting the keys, and delegate to
+    # ActiveRecord::Encryption::Cipher the actual encryption algorithm.
+    class Encryptor
+      # The compressor to use for compressing the payload
+      attr_reader :compressor
+
+      # === Options
+      #
+      # * <tt>:compress</tt> - Boolean indicating whether records should be compressed before encryption.
+      #   Defaults to +true+.
+      # * <tt>:compressor</tt> - The compressor to use.
+      #   1. If compressor is provided, it will be used.
+      #   2. If not, it will use ActiveRecord::Encryption.config.compressor which default value is +Zlib+.
+      #   If you want to use a custom compressor, it must respond to +deflate+ and +inflate+.
+      def initialize(compress: true, compressor: nil)
+        @compress = compress
+        @compressor = compressor || ActiveRecord::Encryption.config.compressor
+      end
+
+      # Encrypts +clean_text+ and returns the encrypted result
+      #
+      # Internally, it will:
+      #
+      # 1. Create a new ActiveRecord::Encryption::Message
+      # 2. Compress and encrypt +clean_text+ as the message payload
+      # 3. Serialize it with +ActiveRecord::Encryption.message_serializer+ (+ActiveRecord::Encryption::SafeMarshal+
+      #    by default)
+      # 4. Encode the result with Base 64
+      #
+      # === Options
+      #
+      # [:key_provider]
+      #   Key provider to use for the encryption operation. It will default to
+      #   +ActiveRecord::Encryption.key_provider+ when not provided.
+      #
+      # [:cipher_options]
+      #   Cipher-specific options that will be passed to the Cipher configured in
+      #   +ActiveRecord::Encryption.cipher+
+      def encrypt(clear_text, key_provider: default_key_provider, cipher_options: {})
+        clear_text = force_encoding_if_needed(clear_text) if cipher_options[:deterministic]
+
+        validate_payload_type(clear_text)
+        serialize_message build_encrypted_message(clear_text, key_provider: key_provider, cipher_options: cipher_options)
+      end
+
+      # Decrypts an +encrypted_text+ and returns the result as clean text
+      #
+      # === Options
+      #
+      # [:key_provider]
+      #   Key provider to use for the encryption operation. It will default to
+      #   +ActiveRecord::Encryption.key_provider+ when not provided
+      #
+      # [:cipher_options]
+      #   Cipher-specific options that will be passed to the Cipher configured in
+      #   +ActiveRecord::Encryption.cipher+
+      def decrypt(encrypted_text, key_provider: default_key_provider, cipher_options: {})
+        message = deserialize_message(encrypted_text)
+        keys = key_provider.decryption_keys(message)
+        raise Errors::Decryption unless keys.present?
+        uncompress_if_needed(cipher.decrypt(message, key: keys.collect(&:secret), **cipher_options), message.headers.compressed)
+      rescue *(ENCODING_ERRORS + DECRYPT_ERRORS)
+        raise Errors::Decryption
+      end
+
+      # Returns whether the text is encrypted or not
+      def encrypted?(text)
+        deserialize_message(text)
+        true
+      rescue Errors::Encoding, *DECRYPT_ERRORS
+        false
+      end
+
+      def binary?
+        serializer.binary?
+      end
+
+      def compress? # :nodoc:
+        @compress
+      end
+
+      private
+        DECRYPT_ERRORS = [OpenSSL::Cipher::CipherError, Errors::EncryptedContentIntegrity, Errors::Decryption]
+        ENCODING_ERRORS = [EncodingError, Errors::Encoding]
+        THRESHOLD_TO_JUSTIFY_COMPRESSION = 140.bytes
+
+        def default_key_provider
+          ActiveRecord::Encryption.key_provider
+        end
+
+        def validate_payload_type(clear_text)
+          unless clear_text.is_a?(String)
+            raise ActiveRecord::Encryption::Errors::ForbiddenClass, "The encryptor can only encrypt string values (#{clear_text.class})"
+          end
+        end
+
+        def cipher
+          ActiveRecord::Encryption.cipher
+        end
+
+        def build_encrypted_message(clear_text, key_provider:, cipher_options:)
+          key = key_provider.encryption_key
+
+          clear_text, was_compressed = compress_if_worth_it(clear_text)
+          cipher.encrypt(clear_text, key: key.secret, **cipher_options).tap do |message|
+            message.headers.add(key.public_tags)
+            message.headers.compressed = true if was_compressed
+          end
+        end
+
+        def serialize_message(message)
+          serializer.dump(message)
+        end
+
+        def deserialize_message(message)
+          serializer.load message
+        rescue ArgumentError, TypeError, Errors::ForbiddenClass
+          raise Errors::Encoding
+        end
+
+        def serializer
+          ActiveRecord::Encryption.message_serializer
+        end
+
+        # Under certain threshold, ZIP compression is actually worse that not compressing
+        def compress_if_worth_it(string)
+          if compress? && string.bytesize > THRESHOLD_TO_JUSTIFY_COMPRESSION
+            [compress(string), true]
+          else
+            [string, false]
+          end
+        end
+
+        def compress(data)
+          @compressor.deflate(data).tap do |compressed_data|
+            compressed_data.force_encoding(data.encoding)
+          end
+        end
+
+        def uncompress_if_needed(data, compressed)
+          if compressed
+            uncompress(data)
+          else
+            data
+          end
+        end
+
+        def uncompress(data)
+          @compressor.inflate(data).tap do |uncompressed_data|
+            uncompressed_data.force_encoding(data.encoding)
+          end
+        end
+
+        def force_encoding_if_needed(value)
+          if forced_encoding_for_deterministic_encryption && value && value.encoding != forced_encoding_for_deterministic_encryption
+            value.encode(forced_encoding_for_deterministic_encryption, invalid: :replace, undef: :replace)
+          else
+            value
+          end
+        end
+
+        def forced_encoding_for_deterministic_encryption
+          ActiveRecord::Encryption.config.forced_encoding_for_deterministic_encryption
+        end
+    end
+  end
+end