aws-sdk-s3 1.207.0 → 1.208.0

data/lib/aws-sdk-s3/encryptionV3/decrypt_handler.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+require 'logger'
+
+module Aws
+  module S3
+    module EncryptionV3
+      # @api private
+      class DecryptHandler < Seahorse::Client::Handler
+        @@warned_response_target_proc = false
+
+        def call(context)
+          attach_http_event_listeners(context)
+          apply_cse_user_agent(context)
+
+          if context[:response_target].is_a?(Proc) && !@@warned_response_target_proc
+            @@warned_response_target_proc = true
+            warn(':response_target is a Proc, or a block was provided. ' \
+              'Read the entire object to the ' \
+              'end before you start using the decrypted data. This is to ' \
+              'verify that the object has not been modified since it ' \
+              'was encrypted.')
+
+          end
+
+          @handler.call(context)
+        end
+
+        private
+
+        def attach_http_event_listeners(context)
+          context.http_response.on_headers(200) do
+            ##= ../specification/s3-encryption/decryption.md#key-commitment
+            ##% The S3EC MUST validate the algorithm suite used for decryption
+            ##% against the key commitment policy before attempting to decrypt the content ciphertext.
+            # This is because the commitment policy _always_ allows decrypting committing algorithms.
+            # In the else branch we check to see if
+            decrypter =
+              if Aws::S3::EncryptionV3::Decryption.v3?(context)
+                ##= ../specification/s3-encryption/data-format/content-metadata.md#determining-s3ec-object-status
+                ##% - If the metadata contains "x-amz-3" and "x-amz-d" and "x-amz-i" then the object MUST be considered an S3EC-encrypted object using the V3 format.
+                cipher, envelope = Aws::S3::EncryptionV3::Decryption.decryption_cipher(context)
+                Aws::S3::EncryptionV3::Decryption.get_decrypter(context, cipher, envelope)
+              else
+                if context[:encryption][:commitment_policy] == :require_encrypt_require_decrypt
+                  ##= ../specification/s3-encryption/decryption.md#key-commitment
+                  ##% If the commitment policy requires decryption using a committing algorithm suite,
+                  ##% and the algorithm suite associated with the object does not support key commitment, then the S3EC MUST throw an exception.
+                  ##= ../specification/s3-encryption/key-commitment.md#commitment-policy
+                  ##% When the commitment policy is REQUIRE_ENCRYPT_REQUIRE_DECRYPT, the S3EC MUST NOT allow decryption using algorithm suites which do not support key commitment.
+                  raise Errors::NonCommittingDecryptionError
+                end
+
+                ##= ../specification/s3-encryption/key-commitment.md#commitment-policy
+                ##% When the commitment policy is FORBID_ENCRYPT_ALLOW_DECRYPT, the S3EC MUST allow decryption using algorithm suites which do not support key commitment.
+                ##= ../specification/s3-encryption/key-commitment.md#commitment-policy
+                ##% When the commitment policy is REQUIRE_ENCRYPT_ALLOW_DECRYPT, the S3EC MUST allow decryption using algorithm suites which do not support key commitment.
+                cipher, envelope = Aws::S3::EncryptionV2::Decryption.decryption_cipher(context)
+                Aws::S3::EncryptionV2::Decryption.get_decrypter(context, cipher, envelope)
+              end
+            context.http_response.body = decrypter
+          end
+
+          context.http_response.on_success(200) do
+            decrypter = context.http_response.body
+            decrypter.finalize
+            decrypter.io.rewind if decrypter.io.respond_to?(:rewind)
+            context.http_response.body = decrypter.io
+          end
+
+          context.http_response.on_error do
+            context.http_response.body = context.http_response.body.io if context.http_response.body.respond_to?(:io)
+          end
+        end
+
+        def apply_cse_user_agent(context)
+          if context.config.user_agent_suffix.nil?
+            context.config.user_agent_suffix = EC_USER_AGENT
+          elsif !context.config.user_agent_suffix.include? EC_USER_AGENT
+            context.config.user_agent_suffix += " #{EC_USER_AGENT}"
+          end
+        end
+      end
+    end
+  end
+end
+
+##= ../specification/s3-encryption/data-format/content-metadata.md#v3-only
+##= type=exception
+##= reason=This has never been supported in Ruby
+##% This material description string MAY be encoded by the esoteric double-encoding scheme used by the S3 web server.
+
+##= ../specification/s3-encryption/data-format/content-metadata.md#v3-only
+##= type=exception
+##= reason=This has never been supported in Ruby
+##% This encryption context string MAY be encoded by the esoteric double-encoding scheme used by the S3 web server.

data/lib/aws-sdk-s3/encryptionV3/decryption.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Aws
+  module S3
+    module EncryptionV3
+      # @api private
+      class Decryption
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##= type=implication
+        ##% The "x-amz-" prefix denotes that the metadata is owned by an Amazon product and MUST be prepended to all S3EC metadata mapkeys.
+
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##% - The mapkey "x-amz-3" MUST be present for V3 format objects.
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##% - The mapkey "x-amz-w" MUST be present for V3 format objects.
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##= type=implication
+        ##% - This mapkey ("x-amz-3") SHOULD be represented by a constant named "ENCRYPTED_DATA_KEY_V3" or similar in the implementation code.
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##= type=implication
+        ##% - This mapkey ("x-amz-w") SHOULD be represented by a constant named "ENCRYPTED_DATA_KEY_ALGORITHM_V3" or similar in the implementation code.
+        ENVELOP_KEY = %w[
+          x-amz-3
+          x-amz-w
+        ].freeze
+
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##% - The mapkey "x-amz-m" SHOULD be present for V3 format objects that use Raw Keyring Material Description.
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##% - The mapkey "x-amz-t" SHOULD be present for V3 format objects that use KMS Encryption Context.
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##= type=implication
+        ##% - This mapkey ("x-amz-m") SHOULD be represented by a constant named "MAT_DESC_V3" or similar in the implementation code.
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##= type=implication
+        ##% - This mapkey ("x-amz-t") SHOULD be represented by a constant named "ENCRYPTION_CONTEXT_V3" or similar in the implementation code.
+        OPTIONAL_ENVELOP_KEY = %w[
+          x-amz-m
+          x-amz-t
+        ].freeze
+
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##% - The mapkey "x-amz-c" MUST be present for V3 format objects.
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##% - The mapkey "x-amz-d" MUST be present for V3 format objects.
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##% - The mapkey "x-amz-i" MUST be present for V3 format objects.
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##= type=implication
+        ##% - This mapkey ("x-amz-c") SHOULD be represented by a constant named "CONTENT_CIPHER_V3" or similar in the implementation code.
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##= type=implication
+        ##% - This mapkey ("x-amz-d") SHOULD be represented by a constant named "KEY_COMMITMENT_V3" or similar in the implementation code.
+        ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+        ##= type=implication
+        ##% - This mapkey ("x-amz-i") SHOULD be represented by a constant named "MESSAGE_ID_V3" or similar in the implementation code.
+        METADATA_KEY = %w[
+          x-amz-c
+          x-amz-d
+          x-amz-i
+        ].freeze
+
+        # Reference V2's envelope keys rather than duplicating them
+        LEGACY_POSSIBLE_ENVELOPE_KEYS = Aws::S3::EncryptionV2::Decryption::POSSIBLE_ENVELOPE_KEYS
+
+        POSSIBLE_ENVELOPE_KEYS = (ENVELOP_KEY + METADATA_KEY + OPTIONAL_ENVELOP_KEY + LEGACY_POSSIBLE_ENVELOPE_KEYS).uniq
+        REQUIRED_ENVELOPE_KEYS = (ENVELOP_KEY + METADATA_KEY).uniq
+
+        POSSIBLE_WRAPPING_FORMATS = %w[
+          01
+          02
+          11
+          12
+          21
+          22
+        ].freeze
+
+        POSSIBLE_ENCRYPTION_FORMATS = %w[
+          115
+        ].freeze
+
+        class << self
+          def v3?(context)
+            context.http_response.headers.key?('x-amz-meta-x-amz-i')
+          end
+
+          def decryption_cipher(context)
+            if (envelope = get_encryption_envelope(context))
+              cipher = context[:encryption][:v3_cipher_provider]
+                       .decryption_cipher(
+                         envelope,
+                         context[:encryption]
+                       )
+              [cipher, envelope]
+            else
+              raise Errors::DecryptionError, 'unable to locate encryption envelope'
+            end
+          end
+
+          # This method fetches the tag from the end of the object by
+          # making a GET Object w/range request. This auth tag is used
+          # to initialize the cipher, and the decrypter truncates the
+          # auth tag from the body when writing the final bytes.
+          def get_decrypter(context, cipher, _envelope)
+            http_resp = context.http_response
+            content_length = http_resp.headers['content-length'].to_i
+
+            # The encrypted object contains both the cipher text
+            # plus a trailing auth tag.
+            # The trailing auth tag will be accumulated and added to the cipher.auth_tag.
+            IOAuthDecrypter.new(
+              io: http_resp.body,
+              encrypted_content_length: content_length - AES_GCM_TAG_LEN_BYTES,
+              cipher: cipher
+            )
+          end
+
+          def get_encryption_envelope(context)
+            # Get initial envelope data from :envelope_location
+            envelope =
+              if context[:encryption][:envelope_location] == :metadata
+                envelope_from_metadata(context)
+              else
+                envelope_from_instr_file(context)
+              end
+
+            # If empty or incomplete, get/merge data from secondary source
+            ##= ../specification/s3-encryption/data-format/content-metadata.md#determining-s3ec-object-status
+            ##% If the object matches none of the V1/V2/V3 formats, the S3EC MUST attempt to get the instruction file.
+            if envelope.nil? || envelope.empty? || !complete_envelop?(envelope)
+              secondary =
+                if context[:encryption][:envelope_location] == :metadata
+                  envelope_from_instr_file(context)
+                else
+                  envelope_from_metadata(context)
+                end
+                # If we attempted to read a non-existent instruction file,
+                # then envelope would be nil,
+                # but we may find the information we need in the metadata.
+                if envelope && secondary
+                  envelope.merge!(secondary)
+                elsif secondary
+                  envelope = secondary
+                end
+            end
+
+            ##= ../specification/s3-encryption/data-format/metadata-strategy.md#object-metadata
+            ##% If the S3EC does not support decoding the S3 Server's "double encoding" then it MUST return the content metadata untouched.
+            v3_envelope?(envelope)
+          end
+
+          def complete_envelop?(possible_envelope)
+            # V3 envelops always store some information in metadata
+            # If we look at the metadata, we may still need to check the instruction file
+            # Similarly, if we start checking the instruction file,
+            # we sill need to get the message id and commitment key from the metadata
+            envelop_count = ENVELOP_KEY.count { |key| possible_envelope.key?(key) }
+            metadata_count = METADATA_KEY.count { |key| possible_envelope.key?(key) }
+
+            # If we have all keys, we are done
+            (envelop_count == ENVELOP_KEY.size && metadata_count == METADATA_KEY.size) ||
+              # If we have 0 keys, then this is done too.
+              # Because it means we are not a v3 committing message.
+              (envelop_count.zero? && metadata_count.zero?)
+          end
+
+          def envelope_from_metadata(context)
+            POSSIBLE_ENVELOPE_KEYS.filter_map do |suffix|
+              ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+              ##= type=exception
+              ##= reason=Ruby is reading the headers directly
+              ##% The "x-amz-meta-" prefix is automatically added by the S3 server and MUST NOT be included in implementation code.
+              if (value = context.http_response.headers["x-amz-meta-#{suffix}"])
+                ##= ../specification/s3-encryption/data-format/metadata-strategy.md#object-metadata
+                ##= type=exception
+                ##= reason=This has never been supported in Ruby
+                ##% The S3EC SHOULD support decoding the S3 Server's "double encoding".
+
+                ##= ../specification/s3-encryption/data-format/metadata-strategy.md#object-metadata
+                ##% If the S3EC does not support decoding the S3 Server's "double encoding" then it MUST return the content metadata untouched.
+                [suffix, value]
+              end
+            end.to_h
+          end
+
+          def envelope_from_instr_file(context)
+            suffix = context[:encryption][:instruction_file_suffix]
+            possible_envelope = Json.load(context.client.get_object(
+              bucket: context.params[:bucket],
+              key: context.params[:key] + suffix
+            ).body.read)
+            unless (keys = possible_envelope.keys & METADATA_KEY).empty?
+              msg = "unsupported metadata key found in instruction file: #{keys.join(', ')}"
+              raise Errors::DecryptionError, msg
+            end
+            possible_envelope
+          rescue S3::Errors::ServiceError, Json::ParseError
+            nil
+          end
+
+          def v3_envelope?(possible_envelope)
+            unless (keys = possible_envelope.keys & LEGACY_POSSIBLE_ENVELOPE_KEYS).empty?
+              ##= ../specification/s3-encryption/data-format/content-metadata.md#determining-s3ec-object-status
+              ##% If there are multiple mapkeys which are meant to be exclusive, such as "x-amz-key", "x-amz-key-v2", and "x-amz-3" then the S3EC SHOULD throw an exception.
+              msg = "legacy metadata key found: #{keys.join(', ')}"
+              raise Errors::DecryptionError, msg
+            end
+
+            unless POSSIBLE_ENCRYPTION_FORMATS.include? possible_envelope['x-amz-c']
+              alg = possible_envelope['x-amz-c'].inspect
+              msg = "unsupported content encrypting key (cek) format: #{alg} #{possible_envelope.inspect}"
+              raise Errors::DecryptionError, msg
+            end
+            unless POSSIBLE_WRAPPING_FORMATS.include? possible_envelope['x-amz-w']
+              alg = possible_envelope['x-amz-w'].inspect
+              msg = "unsupported key wrapping algorithm: #{alg}"
+              raise Errors::DecryptionError, msg
+            end
+            unless (missing_keys = REQUIRED_ENVELOPE_KEYS - possible_envelope.keys).empty?
+              ##= ../specification/s3-encryption/data-format/content-metadata.md#determining-s3ec-object-status
+              ##% In general, if there is any deviation from the above format, with the exception of additional unrelated mapkeys, then the S3EC SHOULD throw an exception.
+              msg = "incomplete v3 encryption envelope:\n"
+              msg += "  missing: #{missing_keys.join(',')}\n"
+              raise Errors::DecryptionError, msg
+            end
+            possible_envelope
+          end
+        end
+      end
+    end
+  end
+end
+
+##= ../specification/s3-encryption/data-format/content-metadata.md#v3-only
+##= type=exception
+##= reason=This has never been supported in Ruby
+##% This material description string MAY be encoded by the esoteric double-encoding scheme used by the S3 web server.
+
+##= ../specification/s3-encryption/data-format/content-metadata.md#v3-only
+##= type=exception
+##= reason=This has never been supported in Ruby
+##% This encryption context string MAY be encoded by the esoteric double-encoding scheme used by the S3 web server.

data/lib/aws-sdk-s3/encryptionV3/default_cipher_provider.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Aws
+  module S3
+    module EncryptionV3
+      # @api private
+      class DefaultCipherProvider
+        def initialize(options = {})
+          @key_provider = options[:key_provider]
+          @key_wrap_schema = validate_key_wrap(
+            options[:key_wrap_schema],
+            @key_provider.encryption_materials.key
+          )
+          ##= ../specification/s3-encryption/encryption.md#content-encryption
+          ##% The S3EC MUST use the encryption algorithm configured during [client](./client.md) initialization.
+          @content_encryption_schema = Utils.validate_cek(
+            options[:content_encryption_schema]
+          )
+        end
+
+        attr_reader :key_provider
+
+        # @return [Array<Hash,Cipher>] Creates an returns a new encryption
+        #   envelope and encryption cipher.
+        def encryption_cipher(options = {})
+          validate_options(options)
+          data_key = Utils.generate_data_key
+          cipher, message_id, commitment_key = Utils.generate_alg_aes_256_gcm_hkdf_sha512_commit_key_cipher(data_key)
+          enc_key =
+            if @key_provider.encryption_materials.key.is_a? OpenSSL::PKey::RSA
+              encode64(
+                encrypt_rsa(data_key, @content_encryption_schema)
+              )
+            else
+              encode64(
+                encrypt_aes_gcm(data_key, @content_encryption_schema)
+              )
+            end
+          ##= ../specification/s3-encryption/data-format/content-metadata.md#algorithm-suite-and-message-format-version-compatibility
+          ##% Objects encrypted with ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY MUST use the V3 message format version only.
+          envelope = {
+            'x-amz-3' => enc_key,
+            'x-amz-c' => @content_encryption_schema,
+            'x-amz-w' => @key_wrap_schema,
+            ##= ../specification/s3-encryption/data-format/content-metadata.md#v3-only
+            ##% The Material Description MUST be used for wrapping algorithms `AES/GCM` (`02`) and `RSA-OAEP-SHA1` (`22`).
+            'x-amz-m' => materials_description,
+            'x-amz-d' => encode64(commitment_key),
+            'x-amz-i' => encode64(message_id)
+          }
+
+          [envelope, cipher]
+        end
+
+        # @return [Cipher] Given an encryption envelope, returns a
+        #   decryption cipher.
+        def decryption_cipher(envelope, options = {})
+          validate_options(options)
+          wrapping_key = @key_provider.key_for(envelope['x-amz-m'])
+
+          data_key =
+            case envelope['x-amz-w']
+            when '02'
+              ##= ../specification/s3-encryption/data-format/content-metadata.md#v3-only
+              ##% - The wrapping algorithm value "02" MUST be translated to AES/GCM upon retrieval, and vice versa on write.
+              if wrapping_key.is_a? OpenSSL::PKey::RSA
+                raise ArgumentError, 'Key mismatch - Client is configured' \
+                  ' with an RSA key and the x-amz-wrap-alg is AES/GCM.'
+              end
+              Utils.decrypt_aes_gcm(wrapping_key,
+                                    decode64(envelope['x-amz-3']),
+                                    @content_encryption_schema)
+            when '22'
+              ##= ../specification/s3-encryption/data-format/content-metadata.md#v3-only
+              ##% - The wrapping algorithm value "22" MUST be translated to RSA-OAEP-SHA1 upon retrieval, and vice versa on write.
+              unless wrapping_key.is_a? OpenSSL::PKey::RSA
+                raise ArgumentError, 'Key mismatch - Client is configured' \
+                  ' with an AES key and the x-amz-wrap-alg is RSA-OAEP-SHA1.'
+              end
+              key, cek_alg = Utils.decrypt_rsa(wrapping_key, decode64(envelope['x-amz-3']))
+              raise Errors::CEKAlgMismatchError unless cek_alg == @content_encryption_schema
+
+              key
+            when '12'
+              raise ArgumentError, 'Key mismatch - Client is configured' \
+                  ' with a user provided key and the x-amz-w is' \
+                  ' kms+context.  Please configure the client with the' \
+                  ' required kms_key_id'
+            else
+              raise ArgumentError, 'Unsupported wrapping algorithm: ' \
+                    "#{envelope['x-amz-w']}"
+            end
+
+          message_id = decode64(envelope['x-amz-i'])
+          commitment_key = decode64(envelope['x-amz-d'])
+
+          Utils.derive_alg_aes_256_gcm_hkdf_sha512_commit_key_cipher(data_key, message_id, commitment_key)
+        end
+
+        private
+
+        # Validate that the key_wrap_schema
+        # is valid, supported and matches the provided key.
+        # Returns the string version for the x-amz-key-wrap-alg
+        def validate_key_wrap(key_wrap_schema, key)
+          if key.is_a? OpenSSL::PKey::RSA
+            unless key_wrap_schema == :rsa_oaep_sha1
+              raise ArgumentError, ':key_wrap_schema must be set to :rsa_oaep_sha1 for RSA keys.'
+            end
+          else
+            unless key_wrap_schema == :aes_gcm
+              raise ArgumentError, ':key_wrap_schema must be set to :aes_gcm for AES keys.'
+            end
+          end
+
+          case key_wrap_schema
+          when :rsa_oaep_sha1 then '22'
+          when :aes_gcm then '02'
+          when :kms_context
+            raise ArgumentError, 'A kms_key_id is required when using :kms_context.'
+          else
+            raise ArgumentError, "Unsupported key_wrap_schema: #{key_wrap_schema}"
+          end
+        end
+
+        def encrypt_aes_gcm(data, auth_data)
+          Utils.encrypt_aes_gcm(@key_provider.encryption_materials.key, data, auth_data)
+        end
+
+        def encrypt_rsa(data, auth_data)
+          Utils.encrypt_rsa(@key_provider.encryption_materials.key, data, auth_data)
+        end
+
+        def materials_description
+          ##= ../specification/s3-encryption/data-format/content-metadata.md#v3-only
+          ##% If the mapkey x-amz-m is not present, the default Material Description value MUST be set to an empty map (`{}`).
+          @key_provider.encryption_materials.description || {}
+        end
+
+        def encode64(str)
+          Base64.encode64(str).split("\n") * ''
+        end
+
+        def decode64(str)
+          Base64.decode64(str)
+        end
+
+        def validate_options(options)
+          return if options[:kms_encryption_context].nil?
+
+          raise ArgumentError, 'Cannot provide :kms_encryption_context ' \
+          'with non KMS client.'
+        end
+      end
+    end
+  end
+end

data/lib/aws-sdk-s3/encryptionV3/default_key_provider.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Aws
+  module S3
+    module EncryptionV3
+      # The default key provider is constructed with a single key
+      # that is used for both encryption and decryption, ignoring
+      # the possible per-object envelope encryption materials description.
+      # @api private
+      class DefaultKeyProvider
+        include KeyProvider
+
+        # @option options [required, OpenSSL::PKey::RSA, String] :encryption_key
+        #   The master key to use for encrypting objects.
+        # @option options [String<JSON>] :materials_description ('{}')
+        #   A description of the encryption key.
+        def initialize(options = {})
+          @encryption_materials = Materials.new(
+            key: options[:encryption_key],
+            description: options[:materials_description] || '{}'
+          )
+        end
+
+        # @return [Materials]
+        attr_reader :encryption_materials
+
+        # @param [String<JSON>] materials_description
+        # @return Returns the key given in the constructor.
+        def key_for(_materials_description)
+          @encryption_materials.key
+        end
+      end
+    end
+  end
+end

data/lib/aws-sdk-s3/encryptionV3/encrypt_handler.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Aws
+  module S3
+    module EncryptionV3
+      # @api private
+      class EncryptHandler < Seahorse::Client::Handler
+        def call(context)
+          envelope, cipher = context[:encryption][:cipher_provider]
+                             .encryption_cipher(
+                               kms_encryption_context: context[:encryption][:kms_encryption_context]
+                             )
+          context[:encryption][:cipher] = cipher
+          apply_encryption_envelope(context, envelope)
+          apply_encryption_cipher(context, cipher)
+          apply_cse_user_agent(context)
+          @handler.call(context)
+        end
+
+        private
+
+        def apply_encryption_envelope(context, envelope)
+          ##= ../specification/s3-encryption/data-format/metadata-strategy.md#instruction-file
+          ##% The S3EC MUST support writing some or all (depending on format) content metadata to an Instruction File.
+          if context[:encryption][:envelope_location] == :instruction_file
+            suffix = context[:encryption][:instruction_file_suffix]
+            instruction_envelop, metadata_envelop = split_for_instruction_file(envelope)
+
+            context.client.put_object(
+              bucket: context.params[:bucket],
+              key: context.params[:key] + suffix,
+              ##= ../specification/s3-encryption/data-format/metadata-strategy.md#instruction-file
+              ##% The content metadata stored in the Instruction File MUST be serialized to a JSON string.
+              ##% The serialized JSON string MUST be the only contents of the Instruction File.
+              body: Json.dump(instruction_envelop)
+            )
+            context.params[:metadata] ||= {}
+            context.params[:metadata].update(metadata_envelop)
+          else
+            context.params[:metadata] ||= {}
+            context.params[:metadata].update(envelope)
+          end
+        end
+
+        def apply_encryption_cipher(context, cipher)
+          io = context.params[:body] || ''
+          io = StringIO.new(io) if io.is_a? String
+          context.params[:body] = IOEncrypter.new(cipher, io)
+          context.params[:metadata] ||= {}
+          # Leaving this in because even though this is years old
+          # it is still important to *not* MD5 the plaintext
+          # If there exists any old integration points still doing this
+          # that upgrade from 1 to 3 this needs to still fail.
+          if context.params.delete(:content_md5)
+            raise ArgumentError, 'Setting content_md5 on client side '\
+              'encrypted objects is deprecated.'
+          end
+          context.http_response.on_headers do
+            context.params[:body].close
+          end
+        end
+
+        def apply_cse_user_agent(context)
+          if context.config.user_agent_suffix.nil?
+            context.config.user_agent_suffix = EC_USER_AGENT
+          elsif !context.config.user_agent_suffix.include? EC_USER_AGENT
+            context.config.user_agent_suffix += " #{EC_USER_AGENT}"
+          end
+        end
+
+        def split_for_instruction_file(envelop)
+          ##= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
+          ##% In the V3 format, the mapkeys "x-amz-c", "x-amz-d", and "x-amz-i" MUST be stored exclusively in the Object Metadata.
+          ##= ../specification/s3-encryption/data-format/metadata-strategy.md#v3-instruction-files
+          ##% - The V3 message format MUST store the mapkey "x-amz-c" and its value in the Object Metadata when writing with an Instruction File.
+          ##% - The V3 message format MUST NOT store the mapkey "x-amz-c" and its value in the Instruction File.
+          ##% - The V3 message format MUST store the mapkey "x-amz-d" and its value in the Object Metadata when writing with an Instruction File.
+          ##% - The V3 message format MUST NOT store the mapkey "x-amz-d" and its value in the Instruction File.
+          ##% - The V3 message format MUST store the mapkey "x-amz-i" and its value in the Object Metadata when writing with an Instruction File.
+          ##% - The V3 message format MUST NOT store the mapkey "x-amz-i" and its value in the Instruction File.
+          metadata_envelop = envelop.select { |k, _v| Decryption::METADATA_KEY.include?(k) }
+          # Exclude the metadata keys rather than include the envelop keys
+          # because there might be additional information
+          ##= ../specification/s3-encryption/data-format/metadata-strategy.md#v3-instruction-files
+          ##% - The V3 message format MUST store the mapkey "x-amz-3" and its value in the Instruction File.
+          ##% - The V3 message format MUST store the mapkey "x-amz-w" and its value in the Instruction File.
+          ##% - The V3 message format MUST store the mapkey "x-amz-m" and its value (when present in the content metadata) in the Instruction File.
+          ##% - The V3 message format MUST store the mapkey "x-amz-t" and its value (when present in the content metadata) in the Instruction File.
+          instruction_envelop = envelop.reject { |k, _v| Decryption::METADATA_KEY.include?(k) }
+
+          [instruction_envelop, metadata_envelop]
+        end
+      end
+    end
+  end
+end