aws-sdk-s3 1.75.0 → 1.76.0

data/lib/aws-sdk-s3/encryption.rb

@@ -17,5 +17,7 @@ require 'aws-sdk-s3/encryption/default_key_provider'
 module Aws
   module S3
     module Encryption; end
+    AES_GCM_TAG_LEN_BYTES = 16
+    EC_USER_AGENT = 'S3CryptoV1n'
   end
 end

data/lib/aws-sdk-s3/encryption/client.rb

@@ -5,6 +5,10 @@ require 'forwardable'
 module Aws
   module S3
 
+    # [MAINTENANCE MODE] There is a new version of the Encryption Client.
+    # AWS strongly recommends upgrading to the {Aws::S3::EncryptionV2::Client},
+    # which provides updated data security best practices.
+    # See documentation for {Aws::S3::EncryptionV2::Client}.
     # Provides an encryption client that encrypts and decrypts data client-side,
     # storing the encrypted data in Amazon S3.
     #
@@ -229,6 +233,13 @@ module Aws
           @envelope_location = extract_location(options)
           @instruction_file_suffix = extract_suffix(options)
         end
+        deprecated :initialize,
+                   message:
+                     '[MAINTENANCE MODE] This version of the S3 Encryption client is currently in maintenance mode. ' \
+	                     'AWS strongly recommends upgrading to the Aws::S3::EncryptionV2::Client, ' \
+	                     'which provides updated data security best practices. ' \
+	                     'See documentation for Aws::S3::EncryptionV2::Client.'
+
 
         # @return [S3::Client]
         attr_reader :client

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

@@ -22,7 +22,17 @@ module Aws
           x-amz-matdesc
         )
 
-        POSSIBLE_ENVELOPE_KEYS = (V1_ENVELOPE_KEYS + V2_ENVELOPE_KEYS).uniq
+        V2_OPTIONAL_KEYS = %w(x-amz-tag-len)
+
+        POSSIBLE_ENVELOPE_KEYS = (V1_ENVELOPE_KEYS +
+          V2_ENVELOPE_KEYS + V2_OPTIONAL_KEYS).uniq
+
+        POSSIBLE_WRAPPING_FORMATS = %w(
+          AES/GCM
+          kms
+          kms+context
+          RSA-OAEP-SHA1
+        )
 
         POSSIBLE_ENCRYPTION_FORMATS = %w(
           AES/GCM/NoPadding
@@ -30,6 +40,8 @@ module Aws
           AES/CBC/PKCS7Padding
         )
 
+        AUTH_REQUIRED_CEK_ALGS = %w(AES/GCM/NoPadding)
+
         def call(context)
           attach_http_event_listeners(context)
           apply_cse_user_agent(context)
@@ -41,9 +53,9 @@ module Aws
         def attach_http_event_listeners(context)
 
           context.http_response.on_headers(200) do
-            cipher = decryption_cipher(context)
-            decrypter = body_contains_auth_tag?(context) ?
-              authenticated_decrypter(context, cipher) :
+            cipher, envelope = decryption_cipher(context)
+            decrypter = body_contains_auth_tag?(envelope) ?
+              authenticated_decrypter(context, cipher, envelope) :
               IODecrypter.new(cipher, context.http_response.body)
             context.http_response.body = decrypter
           end
@@ -64,7 +76,12 @@ module Aws
 
         def decryption_cipher(context)
           if envelope = get_encryption_envelope(context)
-            context[:encryption][:cipher_provider].decryption_cipher(envelope)
+            cipher = context[:encryption][:cipher_provider]
+                     .decryption_cipher(
+                       envelope,
+                       kms_encryption_context: context[:encryption][:kms_encryption_context]
+                     )
+            [cipher, envelope]
           else
             raise Errors::DecryptionError, "unable to locate encryption envelope"
           end
@@ -100,13 +117,12 @@ module Aws
         end
 
         def extract_envelope(hash)
+          return nil unless hash
           return v1_envelope(hash) if hash.key?('x-amz-key')
           return v2_envelope(hash) if hash.key?('x-amz-key-v2')
           if hash.keys.any? { |key| key.match(/^x-amz-key-(.+)$/) }
             msg = "unsupported envelope encryption version #{$1}"
             raise Errors::DecryptionError, msg
-          else
-            nil # no envelope found
           end
         end
 
@@ -120,39 +136,31 @@ module Aws
             msg = "unsupported content encrypting key (cek) format: #{alg}"
             raise Errors::DecryptionError, msg
           end
-          unless envelope['x-amz-wrap-alg'] == 'kms'
-            # possible to support
-            #   RSA/ECB/OAEPWithSHA-256AndMGF1Padding
+          unless POSSIBLE_WRAPPING_FORMATS.include? envelope['x-amz-wrap-alg']
             alg = envelope['x-amz-wrap-alg'].inspect
             msg = "unsupported key wrapping algorithm: #{alg}"
             raise Errors::DecryptionError, msg
           end
-          unless V2_ENVELOPE_KEYS.sort == envelope.keys.sort
+          unless (missing_keys = V2_ENVELOPE_KEYS - envelope.keys).empty?
             msg = "incomplete v2 encryption envelope:\n"
-            msg += "  expected: #{V2_ENVELOPE_KEYS.join(',')}\n"
-            msg += "  got: #{envelope_keys.join(', ')}"
+            msg += "  missing: #{missing_keys.join(',')}\n"
             raise Errors::DecryptionError, msg
           end
           envelope
         end
 
-        # When the x-amz-meta-x-amz-tag-len header is present, it indicates
-        # that the body of this object has a trailing auth tag. The header
-        # indicates the length of that tag.
-        #
         # 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 authenticated_decrypter(context, cipher)
+        def authenticated_decrypter(context, cipher, envelope)
           if RUBY_VERSION.match(/1.9/)
-            raise "authenticated decryption not supported by OpeenSSL in Ruby version ~> 1.9"
+            raise "authenticated decryption not supported by OpenSSL in Ruby version ~> 1.9"
             raise Aws::Errors::NonSupportedRubyVersionError, msg
           end
           http_resp = context.http_response
           content_length = http_resp.headers['content-length'].to_i
-          auth_tag_length = http_resp.headers['x-amz-meta-x-amz-tag-len']
-          auth_tag_length = auth_tag_length.to_i / 8
+          auth_tag_length = auth_tag_length(envelope)
 
           auth_tag = context.client.get_object(
             bucket: context.params[:bucket],
@@ -164,23 +172,39 @@ module Aws
           cipher.auth_data = ''
 
           # The encrypted object contains both the cipher text
-          # plus a trailing auth tag. This decrypter will the body
-          # expect for the trailing auth tag.
+          # plus a trailing auth tag.
           IOAuthDecrypter.new(
             io: http_resp.body,
             encrypted_content_length: content_length - auth_tag_length,
             cipher: cipher)
         end
 
-        def body_contains_auth_tag?(context)
-          context.http_response.headers['x-amz-meta-x-amz-tag-len']
+        def body_contains_auth_tag?(envelope)
+          AUTH_REQUIRED_CEK_ALGS.include?(envelope['x-amz-cek-alg'])
+        end
+
+        # Determine the auth tag length from the algorithm
+        # Validate it against the value provided in the x-amz-tag-len
+        # Return the tag length in bytes
+        def auth_tag_length(envelope)
+          tag_length =
+            case envelope['x-amz-cek-alg']
+            when 'AES/GCM/NoPadding' then AES_GCM_TAG_LEN_BYTES
+            else
+              raise ArgumentError, 'Unsupported cek-alg: ' \
+                "#{envelope['x-amz-cek-alg']}"
+            end
+          if (tag_length * 8) != envelope['x-amz-tag-len'].to_i
+            raise Errors::DecryptionError, 'x-amz-tag-len does not match expected'
+          end
+          tag_length
         end
 
         def apply_cse_user_agent(context)
           if context.config.user_agent_suffix.nil?
-            context.config.user_agent_suffix = 'CSE_V1'
-          elsif !context.config.user_agent_suffix.include? 'CSE_V1'
-            context.config.user_agent_suffix += ' CSE_V1'
+            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
 

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

@@ -26,11 +26,48 @@ module Aws
 
         # @return [Cipher] Given an encryption envelope, returns a
         #   decryption cipher.
-        def decryption_cipher(envelope)
+        def decryption_cipher(envelope, options = {})
           master_key = @key_provider.key_for(envelope['x-amz-matdesc'])
-          key = Utils.decrypt(master_key, decode64(envelope['x-amz-key']))
-          iv = decode64(envelope['x-amz-iv'])
-          Utils.aes_decryption_cipher(:CBC, key, iv)
+          if envelope.key? 'x-amz-key'
+            # Support for decryption of legacy objects
+            key = Utils.decrypt(master_key, decode64(envelope['x-amz-key']))
+            iv = decode64(envelope['x-amz-iv'])
+            Utils.aes_decryption_cipher(:CBC, key, iv)
+          else
+            if envelope['x-amz-cek-alg'] != 'AES/GCM/NoPadding'
+              raise ArgumentError, 'Unsupported cek-alg: ' \
+                "#{envelope['x-amz-cek-alg']}"
+            end
+            key =
+              case envelope['x-amz-wrap-alg']
+              when 'AES/GCM'
+                if master_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(master_key,
+                                      decode64(envelope['x-amz-key-v2']),
+                                      envelope['x-amz-cek-alg'])
+              when 'RSA-OAEP-SHA1'
+                unless master_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(master_key, decode64(envelope['x-amz-key-v2']))
+                raise Errors::DecryptionError unless cek_alg == envelope['x-amz-cek-alg']
+                key
+              when 'kms+context'
+                raise ArgumentError, 'Key mismatch - Client is configured' \
+                    ' with a user provided key and the x-amz-wrap-alg is' \
+                    ' kms+context.  Please configure the client with the' \
+                    ' required kms_key_id'
+              else
+                raise ArgumentError, 'Unsupported wrap-alg: ' \
+                "#{envelope['x-amz-wrap-alg']}"
+              end
+            iv = decode64(envelope['x-amz-iv'])
+            Utils.aes_decryption_cipher(:GCM, key, iv)
+          end
         end
 
         private
@@ -58,7 +95,6 @@ module Aws
         def decode64(str)
           Base64.decode64(str)
         end
-
       end
     end
   end

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

@@ -39,8 +39,8 @@ module Aws
           context.params[:body] = IOEncrypter.new(cipher, io)
           context.params[:metadata] ||= {}
           context.params[:metadata]['x-amz-unencrypted-content-length'] = io.size
-          if md5 = context.params.delete(:content_md5)
-            context.params[:metadata]['x-amz-unencrypted-content-md5'] = md5
+          if context.params.delete(:content_md5)
+            warn('Setting content_md5 on client side encrypted objects is deprecated')
           end
           context.http_response.on_headers do
             context.params[:body].close
@@ -49,9 +49,9 @@ module Aws
 
         def apply_cse_user_agent(context)
           if context.config.user_agent_suffix.nil?
-            context.config.user_agent_suffix = 'CSE_V1'
-          elsif !context.config.user_agent_suffix.include? 'CSE_V1'
-            context.config.user_agent_suffix += ' CSE_V1'
+            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
 

data/lib/aws-sdk-s3/encryption/kms_cipher_provider.rb

@@ -36,15 +36,36 @@ module Aws
 
         # @return [Cipher] Given an encryption envelope, returns a
         #   decryption cipher.
-        def decryption_cipher(envelope)
+        def decryption_cipher(envelope, options = {})
           encryption_context = Json.load(envelope['x-amz-matdesc'])
+          cek_alg = envelope['x-amz-cek-alg']
+
+          case envelope['x-amz-wrap-alg']
+          when 'kms'; # NO OP
+          when 'kms+context'
+            if cek_alg != encryption_context['aws:x-amz-cek-alg']
+              raise Errors::DecryptionError, 'Value of cek-alg from envelope'\
+              ' does not match the value in the encryption context'
+            end
+          when 'AES/GCM'
+            raise ArgumentError, 'Key mismatch - Client is configured' \
+                    ' with a KMS key and the x-amz-wrap-alg is AES/GCM.'
+          when 'RSA-OAEP-SHA1'
+            raise ArgumentError, 'Key mismatch - Client is configured' \
+                    ' with a KMS key and the x-amz-wrap-alg is RSA-OAEP-SHA1.'
+          else
+            raise ArgumentError, 'Unsupported wrap-alg: ' \
+                "#{envelope['x-amz-wrap-alg']}"
+          end
+
           key = @kms_client.decrypt(
             ciphertext_blob: decode64(envelope['x-amz-key-v2']),
-            encryption_context: encryption_context,
+            encryption_context: encryption_context
           ).plaintext
+
           iv = decode64(envelope['x-amz-iv'])
           block_mode =
-            case envelope['x-amz-cek-alg']
+            case cek_alg
             when 'AES/CBC/PKCS5Padding'
               :CBC
             when 'AES/CBC/PKCS7Padding'
@@ -61,6 +82,14 @@ module Aws
 
         private
 
+        def build_encryption_context(cek_alg, options = {})
+          kms_context = (options[:kms_encryption_context] || {})
+                        .each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+          {
+            'aws:x-amz-cek-alg' => cek_alg
+          }.merge(kms_context)
+        end
+
         def encode64(str)
           Base64.encode64(str).split("\n") * ""
         end

data/lib/aws-sdk-s3/encryption/utils.rb

@@ -39,6 +39,29 @@ module Aws
             end
           end
 
+
+          def decrypt_aes_gcm(key, data, auth_data)
+            # data is iv (12B) + key + tag (16B)
+            buf = data.unpack('C*')
+            iv = buf[0,12].pack('C*') # iv will always be 12 bytes
+            tag = buf[-16, 16].pack('C*') # tag is 16 bytes
+            enc_key = buf[12, buf.size - (12+16)].pack('C*')
+            cipher = aes_cipher(:decrypt, :GCM, key, iv)
+            cipher.auth_tag = tag
+            cipher.auth_data = auth_data
+            cipher.update(enc_key) + cipher.final
+          end
+
+          # returns the decrypted data + auth_data
+          def decrypt_rsa(key, enc_data)
+            # Plaintext must be KeyLengthInBytes (1 Byte) + DataKey + AuthData
+            buf = key.private_decrypt(enc_data, OpenSSL::PKey::RSA::PKCS1_OAEP_PADDING).unpack('C*')
+            key_length = buf[0]
+            data = buf[1, key_length].pack('C*')
+            auth_data = buf[key_length+1, buf.length - key_length].pack('C*')
+            [data, auth_data]
+          end
+
           # @param [String] block_mode "CBC" or "ECB"
           # @param [OpenSSL::PKey::RSA, String, nil] key
           # @param [String, nil] iv The initialization vector

data/lib/aws-sdk-s3/encryptionV2/client.rb

@@ -1,16 +1,20 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 
 module Aws
   module S3
 
+    REQUIRED_PARAMS = [:key_wrap_schema, :content_encryption_schema, :security_profile]
+    SUPPORTED_SECURITY_PROFILES = [:v2, :v2_and_legacy]
+
     # Provides an encryption client that encrypts and decrypts data client-side,
-    # storing the encrypted data in Amazon S3.  The EncryptionV2::Client
-    # provides improved security over the Encryption::Client by using more
-    # modern and secure algorithms.  The EncryptionV2::Client maintains
-    # backwards compatibility: Using the EncryptionV2::Client you can decrypt
-    # objects encrypted with the Encryption::Client.  However, objects you
-    # encrypt using the EncryptionV2::Client cannot be decrypted using the
-    # Encryption::Client.
+    # storing the encrypted data in Amazon S3.  The `EncryptionV2::Client` (V2 Client)
+    # provides improved security over the `Encryption::Client` (V1 Client)
+    # by using more modern and secure algorithms. You can use the V2 Client
+    # to continue decrypting objects encrypted using deprecated algorithms
+    # by setting security_profile: :v2_and_legacy. The latest V1 Client also
+    # supports reading and decrypting objects encrypted by the V2 Client.
     #
     # This client uses a process called "envelope encryption". Your private
     # encryption keys and your data's plain-text are **never** sent to
@@ -47,7 +51,12 @@ module Aws
     #     key = OpenSSL::PKey::RSA.new(1024)
     #
     #     # encryption client
-    #     s3 = Aws::S3::EncryptionV2::Client.new(encryption_key: key)
+    #     s3 = Aws::S3::EncryptionV2::Client.new(
+    #       encryption_key: key,
+    #       key_wrap_schema: :rsa_oaep_sha1, # the key_wrap_schema must be rsa_oaep_sha1 for asymmetric keys
+    #       content_encryption_schema: :aes_gcm_no_padding,
+    #       security_profile: :v2 # use :v2_and_legacy to allow reading/decrypting objects encrypted by the V1 encryption client
+    #     )
     #
     #     # round-trip an object, encrypted/decrypted locally
     #     s3.put_object(bucket:'aws-sdk', key:'secret', body:'handshake')
@@ -59,6 +68,19 @@ module Aws
     #     Aws::S3::Client.new.get_object(bucket:'aws-sdk', key:'secret').body.read
     #     #=> "... cipher text ..."
     #
+    # ## Required Configuration
+    #
+    # You must configure all of the following:
+    # * a key or key provider - See the Keys section below. The key provided determines
+    #   the key wrapping schema(s) supported for both encryption and decryption.
+    # * `key_wrap_schema` - The key wrapping schema. It must match the type of key configured.
+    # * `content_encryption_schema` - The only supported value currently is `:aes_gcm_no_padding`.
+    #    More options will be added in future releases.
+    # * `security_profile` - Determines the support for reading objects written
+    #    using older key wrap or content encryption schemas. If you need to read
+    #    legacy objects encrypted by an existing V1 Client, then set this to `:v2_and_legacy`.
+    #    Otherwise, set it to `:v2`
+    #
     # ## Keys
     #
     # For client-side encryption to work, you must provide one of the following:
@@ -67,15 +89,25 @@ module Aws
     # * A {KeyProvider}
     # * A KMS encryption key id
     #
+    # Additionally, the key wrapping schema must agree with the type of the key:
+    # * :aes_gcm: An AES encryption key or a key provider.
+    # * :rsa_oaep_sha1: An RSA encryption key or key provider.
+    # * :kms_context: A KMS encryption key id
+    #
     # ### An Encryption Key
     #
     # You can pass a single encryption key. This is used as a master key
     # encrypting and decrypting all object keys.
     #
-    #     key = OpenSSL::Cipher.new("AES-256-ECB").random_key # symmetric key
-    #     key = OpenSSL::PKey::RSA.new(1024) # asymmetric key pair
+    #     key = OpenSSL::Cipher.new("AES-256-ECB").random_key # symmetric key - used with `key_wrap_schema: :aes_gcm`
+    #     key = OpenSSL::PKey::RSA.new(1024) # asymmetric key pair - used with `key_wrap_schema: :rsa_oaep_sha1`
     #
-    #     s3 = Aws::S3::EncryptionV2::Client.new(encryption_key: key)
+    #     s3 = Aws::S3::EncryptionV2::Client.new(
+    #       encryption_key: key,
+    #       key_wrap_schema: :aes_gcm, # or :rsa_oaep_sha1 if using RSA
+    #       content_encryption_schema: :aes_gcm_no_padding,
+    #       security_profile: :v2
+    #     )
     #
     # ### Key Provider
     #
@@ -84,8 +116,9 @@ module Aws
     #
     # ### KMS Encryption Key Id
     #
-    # If you pass the id to an AWS Key Management Service (KMS) key,
-    # then KMS will be used to generate, encrypt and decrypt object keys.
+    # If you pass the id of an AWS Key Management Service (KMS) key and
+    # use :kms_content for the key_wrap_schema, then KMS will be used to
+    # generate, encrypt and decrypt object keys.
     #
     #     # keep track of the kms key id
     #     kms = Aws::KMS::Client.new
@@ -94,6 +127,9 @@ module Aws
     #     Aws::S3::EncryptionV2::Client.new(
     #       kms_key_id: key_id,
     #       kms_client: kms,
+    #       key_wrap_schema: :kms_context,
+    #       content_encryption_schema: :aes_gcm_no_padding,
+    #       security_profile: :v2
     #     )
     #
     # ## Custom Key Providers
@@ -142,7 +178,12 @@ module Aws
     #
     #     # chooses the key based on the materials description stored
     #     # with the encrypted object
-    #     s3 = Aws::S3::EncryptionV2::Client.new(key_provider: keys)
+    #     s3 = Aws::S3::EncryptionV2::Client.new(
+    #       key_provider: keys,
+    #       key_wrap_schema: ...,
+    #       content_encryption_schema: :aes_gcm_no_padding,
+    #       security_profile: :v2
+    #     )
     #
     # ## Materials Description
     #
@@ -176,6 +217,9 @@ module Aws
     #       key_provider: ...,
     #       envelope_location: :instruction_file,
     #       instruction_file_suffix: '.instruction' # default
+    #       key_wrap_schema: ...,
+    #       content_encryption_schema: :aes_gcm_no_padding,
+    #       security_profile: :v2
     #     )
     #
     # When using an instruction file, multiple requests are made when
@@ -189,8 +233,18 @@ module Aws
         extend Forwardable
         def_delegators :@client, :config, :delete_object, :head_object, :build_request
 
-        # Creates a new encryption client. You must provide one of the following
-        # options:
+        # Creates a new encryption client. You must configure all of the following:
+        # * a key or key provider - The key provided also determines the key wrapping
+        #   schema(s) supported for both encryption and decryption.
+        # * `key_wrap_schema` - The key wrapping schema. It must match the type of key configured.
+        # * `content_encryption_schema` - The only supported value currently is `:aes_gcm_no_padding`
+        #    More options will be added in future releases.
+        # * `security_profile` - Determines the support for reading objects written
+        #    using older key wrap or content encryption schemas. If you need to read
+        #    legacy objects encrypted by an existing V1 Client, then set this to `:v2_and_legacy`.
+        #    Otherwise, set it to `:v2`
+        #
+        # To configure the key you must provide one of the following set of options:
         #
         # * `:encryption_key`
         # * `:kms_key_id`
@@ -209,12 +263,36 @@ module Aws
         #   then AWS Key Management Service (KMS) will be used to manage the
         #   object encryption keys. By default a {KMS::Client} will be
         #   constructed for KMS API calls. Alternatively, you can provide
-        #   your own via `:kms_client`.
+        #   your own via `:kms_client`. To only support decryption/reads, you may
+        #   provide `:allow_decrypt_with_any_cmk` which will use
+        #   the implicit CMK associated with the data during reads but will
+        #   not allow you to encrypt/write objects with this client.
         #
         # @option options [#key_for] :key_provider Any object that responds
         #   to `#key_for`. This method should accept a materials description
         #   JSON document string and return return an encryption key.
         #
+        # @option options [required, Symbol] :key_wrap_schema The Key wrapping
+        #   schema to be used. It must match the type of key configured.
+        #   Must be one of the following:
+        #
+        #   * :kms_context  (Must provide kms_key_id)
+        #   * :aes_gcm (Must provide an AES (string) key)
+        #   * :rsa_oaep_sha1 (Must provide an RSA key)
+        #
+        # @option options [required, Symbol] :content_encryption_schema
+        #   Must be one of the following:
+        #
+        #   * :aes_gcm_no_padding
+        #
+        # @option options [Required, Symbol] :security_profile
+        #   Determines the support for reading objects written using older
+        #   key wrap or content encryption schemas.
+        #   Must be one of the following:
+        #
+        #   * :v2 - Reads of legacy (v1) objects are NOT allowed
+        #   * :v2_and_legacy - Enables reading of legacy (V1) schemas.
+        #
         # @option options [Symbol] :envelope_location (:metadata) Where to
         #   store the envelope encryption keys. By default, the envelope is
         #   stored with the encrypted object. If you pass `:instruction_file`,
@@ -228,10 +306,14 @@ module Aws
         #   is constructed when using KMS to manage encryption keys.
         #
         def initialize(options = {})
+          validate_params(options)
           @client = extract_client(options)
           @cipher_provider = cipher_provider(options)
           @envelope_location = extract_location(options)
           @instruction_file_suffix = extract_suffix(options)
+          @kms_allow_decrypt_with_any_cmk =
+            options[:kms_key_id] == :kms_allow_decrypt_with_any_cmk
+          @security_profile = extract_security_profile(options)
         end
 
         # @return [S3::Client]
@@ -241,6 +323,14 @@ module Aws
         #   AWS Key Management Service (KMS).
         attr_reader :key_provider
 
+        # @return [Symbol] Determines the support for reading objects written
+        #   using older key wrap or content encryption schemas.
+        attr_reader :security_profile
+
+        # @return [Boolean] If true the provided KMS key_id will not be used
+        #   during decrypt, allowing decryption with the key_id from the object.
+        attr_reader :kms_allow_decrypt_with_any_cmk
+
         # @return [Symbol<:metadata, :instruction_file>]
         attr_reader :envelope_location
 
@@ -272,9 +362,22 @@ module Aws
           req.send_request
         end
 
-        # Gets an object from Amazon S3, decrypting  data locally.
+        # Gets an object from Amazon S3, decrypting data locally.
         # See {S3::Client#get_object} for documentation on accepted
         # request parameters.
+        # Warning: If you provide a block to get_object or set the request
+        # parameter :response_target to a Proc, then 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.
+        #
+        # @option options [Symbol] :security_profile
+        #   Determines the support for reading objects written using older
+        #   key wrap or content encryption schemas. Overrides the value set
+        #   on client construction if provided.
+        #   Must be one of the following:
+        #
+        #   * :v2 - Reads of legacy (v1) objects are NOT allowed
+        #   * :v2_and_legacy - Enables reading of legacy (V1) schemas.
         # @option params [String] :instruction_file_suffix The suffix
         #   used to find the instruction file containing the encryption
         #   envelope. You should not set this option when the envelope
@@ -282,7 +385,10 @@ module Aws
         #   {#instruction_file_suffix}.
         # @option params [Hash] :kms_encryption_context Additional encryption
         #   context to use with KMS.  Applies only when KMS is used.
-        # @option params [String] :instruction_file_suffix
+        # @option options [Boolean] :kms_allow_decrypt_with_any_cmk (false)
+        #   By default the KMS CMK ID (kms_key_id) will be used during decrypt
+        #   and will fail if there is a mismatch.  Setting this to true
+        #   will use the implicit CMK associated with the data.
         # @option (see S3::Client#get_object)
         # @return (see S3::Client#get_object)
         # @see S3::Client#get_object
@@ -293,19 +399,44 @@ module Aws
           end
           envelope_location, instruction_file_suffix = envelope_options(params)
           kms_encryption_context = params.delete(:kms_encryption_context)
+          kms_any_cmk_mode = kms_any_cmk_mode(params)
+          security_profile = security_profile_from_params(params)
+
           req = @client.build_request(:get_object, params)
           req.handlers.add(DecryptHandler)
           req.context[:encryption] = {
             cipher_provider: @cipher_provider,
             envelope_location: envelope_location,
             instruction_file_suffix: instruction_file_suffix,
-            kms_encryption_context: kms_encryption_context
+            kms_encryption_context: kms_encryption_context,
+            kms_allow_decrypt_with_any_cmk: kms_any_cmk_mode,
+            security_profile: security_profile
           }
           req.send_request(target: block)
         end
 
         private
 
+        # Validate required parameters exist and don't conflict.
+        # The cek_alg and wrap_alg are passed on to the CipherProviders
+        # and further validated there
+        def validate_params(options)
+          unless (missing_params = REQUIRED_PARAMS - options.keys).empty?
+            raise ArgumentError, "Missing required parameter(s): "\
+              "#{missing_params.map{ |s| ":#{s}" }.join(', ')}"
+          end
+
+          wrap_alg = options[:key_wrap_schema]
+
+          # validate that the wrap alg matches the type of key given
+          case wrap_alg
+          when :kms_context
+            unless options[:kms_key_id]
+              raise ArgumentError, 'You must provide :kms_key_id to use :kms_context'
+            end
+          end
+        end
+
         def extract_client(options)
           options[:client] || begin
             options = options.dup
@@ -315,6 +446,7 @@ module Aws
             options.delete(:encryption_key)
             options.delete(:envelope_location)
             options.delete(:instruction_file_suffix)
+            REQUIRED_PARAMS.each { |p| options.delete(p) }
             S3::Client.new(options)
           end
         end
@@ -324,7 +456,7 @@ module Aws
             KMS::Client.new(
               region: @client.config.region,
               credentials: @client.config.credentials,
-            )
+              )
           end
         end
 
@@ -333,10 +465,16 @@ module Aws
             KmsCipherProvider.new(
               kms_key_id: options[:kms_key_id],
               kms_client: kms_client(options),
+              key_wrap_schema: options[:key_wrap_schema],
+              content_encryption_schema: options[:content_encryption_schema]
             )
           else
             @key_provider = extract_key_provider(options)
-            DefaultCipherProvider.new(key_provider: @key_provider)
+            DefaultCipherProvider.new(
+              key_provider: @key_provider,
+              key_wrap_schema: options[:key_wrap_schema],
+              content_encryption_schema: options[:content_encryption_schema]
+            )
           end
         end
 
@@ -382,6 +520,44 @@ module Aws
           end
         end
 
+        def kms_any_cmk_mode(params)
+          if !params[:kms_allow_decrypt_with_any_cmk].nil?
+            params.delete(:kms_allow_decrypt_with_any_cmk)
+          else
+            @kms_allow_decrypt_with_any_cmk
+          end
+        end
+
+        def extract_security_profile(options)
+          validate_security_profile(options[:security_profile])
+        end
+
+        def security_profile_from_params(params)
+          security_profile =
+            if !params[:security_profile].nil?
+              params.delete(:security_profile)
+            else
+              @security_profile
+            end
+          validate_security_profile(security_profile)
+        end
+
+        def validate_security_profile(security_profile)
+          unless SUPPORTED_SECURITY_PROFILES.include? security_profile
+            raise ArgumentError, "Unsupported security profile: :#{security_profile}. " \
+            "Please provide one of: #{SUPPORTED_SECURITY_PROFILES.map { |s| ":#{s}" }.join(', ')}"
+          end
+          if security_profile == :v2_and_legacy && !@warned_about_legacy
+            @warned_about_legacy = true
+            warn(
+              'The S3 Encryption Client is configured to read encrypted objects ' \
+              "with legacy encryption modes. If you don't have objects " \
+              'encrypted with these legacy modes, you should disable support ' \
+              'for them to enhance security.'
+            )
+          end
+          security_profile
+        end
       end
     end
   end