# frozen_string_literal: true

require 'forwardable'

module Aws
  module S3

    REQUIRED_PARAMS = [:key_wrap_schema, :content_encryption_schema, :security_profile].freeze
    SUPPORTED_SECURITY_PROFILES = [:v2, :v2_and_legacy].freeze
    SUPPORTED_COMMITMENT_POLICIES = [:forbid_encrypt_allow_decrypt].freeze

    # [MAINTENANCE MODE] There is a new version of the Encryption Client.
    # AWS strongly recommends upgrading to the {Aws::S3::EncryptionV3::Client},
    # which provides updated data security best practices.
    # For migration guidance, see: https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/s3-encryption-migration-v2-v3.html
    # Provides an encryption client that encrypts and decrypts data client-side,
    # storing the encrypted data in Amazon S3.
    # 
    # Provides an encryption client that encrypts and decrypts data client-side,
    # 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
    # Amazon S3. **If you lose you encryption keys, you will not be able to
    # decrypt your data.**
    #
    # ## Envelope Encryption Overview
    #
    # The goal of envelope encryption is to combine the performance of
    # fast symmetric encryption while maintaining the secure key management
    # that asymmetric keys provide.
    #
    # A one-time-use symmetric key (envelope key) is generated client-side.
    # This is used to encrypt the data client-side. This key is then
    # encrypted by your master key and stored alongside your data in Amazon
    # S3.
    #
    # When accessing your encrypted data with the encryption client,
    # the encrypted envelope key is retrieved and decrypted client-side
    # with your master key. The envelope key is then used to decrypt the
    # data client-side.
    #
    # One of the benefits of envelope encryption is that if your master key
    # is compromised, you have the option of just re-encrypting the stored
    # envelope symmetric keys, instead of re-encrypting all of the
    # data in your account.
    #
    # ## Basic Usage
    #
    # The encryption client requires an {Aws::S3::Client}. If you do not
    # provide a `:client`, then a client will be constructed for you.
    #
    #     require 'openssl'
    #     key = OpenSSL::PKey::RSA.new(1024)
    #
    #     # encryption client
    #     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')
    #     s3.get_object(bucket:'aws-sdk', key:'secret').body.read
    #     #=> 'handshake'
    #
    #     # reading encrypted object without the encryption client
    #     # results in the getting the cipher text
    #     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:
    #
    # * An encryption key
    # * 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 - 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,
    #       key_wrap_schema: :aes_gcm, # or :rsa_oaep_sha1 if using RSA
    #       content_encryption_schema: :aes_gcm_no_padding,
    #       security_profile: :v2
    #     )
    #
    # ### Key Provider
    #
    # Alternatively, you can use a {KeyProvider}. A key provider makes
    # it easy to work with multiple keys and simplifies key rotation.
    #
    # ### KMS Encryption Key Id
    #
    # 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
    #     key_id = kms.create_key.key_metadata.key_id
    #
    #     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
    #
    # A {KeyProvider} is any object that responds to:
    #
    # * `#encryption_materials`
    # * `#key_for(materials_description)`
    #
    # Here is a trivial implementation of an in-memory key provider.
    # This is provided as a demonstration of the key provider interface,
    # and should not be used in production:
    #
    #     class KeyProvider
    #
    #       def initialize(default_key_name, keys)
    #         @keys = keys
    #         @encryption_materials = Aws::S3::EncryptionV2::Materials.new(
    #           key: @keys[default_key_name],
    #           description: JSON.dump(key: default_key_name),
    #         )
    #       end
    #
    #       attr_reader :encryption_materials
    #
    #       def key_for(matdesc)
    #         key_name = JSON.parse(matdesc)['key']
    #         if key = @keys[key_name]
    #           key
    #         else
    #           raise "encryption key not found for: #{matdesc.inspect}"
    #         end
    #       end
    #     end
    #
    # Given the above key provider, you can create an encryption client that
    # chooses the key to use based on the materials description stored with
    # the encrypted object. This makes it possible to use multiple keys
    # and simplifies key rotation.
    #
    #     # uses "new-key" for encrypting objects, uses either for decrypting
    #     keys = KeyProvider.new('new-key', {
    #       "old-key" => Base64.decode64("kM5UVbhE/4rtMZJfsadYEdm2vaKFsmV2f5+URSeUCV4="),
    #       "new-key" => Base64.decode64("w1WLio3agRWRTSJK/Ouh8NHoqRQ6fn5WbSXDTHjXMSo="),
    #     }),
    #
    #     # chooses the key based on the materials description stored
    #     # with the encrypted object
    #     s3 = Aws::S3::EncryptionV2::Client.new(
    #       key_provider: keys,
    #       key_wrap_schema: ...,
    #       content_encryption_schema: :aes_gcm_no_padding,
    #       security_profile: :v2
    #     )
    #
    # ## Materials Description
    #
    # A materials description is JSON document string that is stored
    # in the metadata (or instruction file) of an encrypted object.
    # The {DefaultKeyProvider} uses the empty JSON document `"{}"`.
    #
    # When building a key provider, you are free to store whatever
    # information you need to identify the master key that was used
    # to encrypt the object.
    #
    # ## Envelope Location
    #
    # By default, the encryption client store the encryption envelope
    # with the object, as metadata. You can choose to have the envelope
    # stored in a separate "instruction file". An instruction file
    # is an object, with the key of the encrypted object, suffixed with
    # `".instruction"`.
    #
    # Specify the `:envelope_location` option as `:instruction_file` to
    # use an instruction file for storing the envelope.
    #
    #     # default behavior
    #     s3 = Aws::S3::EncryptionV2::Client.new(
    #       key_provider: ...,
    #       envelope_location: :metadata,
    #     )
    #
    #     # store envelope in a separate object
    #     s3 = Aws::S3::EncryptionV2::Client.new(
    #       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
    # putting and getting the object. **This may cause issues if you are
    # issuing concurrent PUT and GET requests to an encrypted object.**
    #
    module EncryptionV2
      class Client

        extend Deprecations
        extend Forwardable
        def_delegators :@client, :config, :delete_object, :head_object, :build_request

        # 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`
        # * `:key_provider`
        #
        # You may also pass any other options accepted by `Client#initialize`.
        #
        # @option options [S3::Client] :client A basic S3 client that is used
        #   to make api calls. If a `:client` is not provided, a new {S3::Client}
        #   will be constructed.
        #
        # @option options [OpenSSL::PKey::RSA, String] :encryption_key The master
        #   key to use for encrypting/decrypting all objects.
        #
        # @option options [String] :kms_key_id When you provide a `:kms_key_id`,
        #   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`. 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`,
        #   then the envelope is stored in a separate object in Amazon S3.
        #
        # @option options [String] :instruction_file_suffix ('.instruction')
        #   When `:envelope_location` is `:instruction_file` then the
        #   instruction file uses the object key with this suffix appended.
        #
        # @option options [KMS::Client] :kms_client A default {KMS::Client}
        #   is constructed when using KMS to manage encryption keys.
        #
        # @option options [Symbol] :commitment_policy (nil)
        #   Optional parameter for migration from V2 to V3. When set to
        #   :forbid_encrypt_allow_decrypt, this explicitly indicates you are
        #   maintaining V2 encryption behavior while preparing for migration.
        #   This allows the V2 client to decrypt V3-encrypted objects while
        #   continuing to encrypt new objects using V2 algorithms.
        #   Only :forbid_encrypt_allow_decrypt is supported.
        #   For migration guidance, see: https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/s3-encryption-migration-v2-v3.html
        #
        def initialize(options = {})
          validate_params(options)
          @client = extract_client(options)
          @cipher_provider = build_cipher_provider(options)
          @key_provider = @cipher_provider.key_provider if @cipher_provider.is_a?(DefaultCipherProvider)
          @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)
          @commitment_policy = extract_commitment_policy(options)
          # The v3 cipher is only used for decrypt.
          # Therefore any configured v2 `content_encryption_schema` is going to be incorrect.
          @v3_cipher_provider = build_v3_cipher_provider_for_decrypt(options.reject { |k, _| k == :content_encryption_schema })
        end

        # @return [S3::Client]
        attr_reader :client

        # @return [KeyProvider, nil] Returns `nil` if you are using
        #   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

        # @return [String] When {#envelope_location} is `:instruction_file`,
        #   the envelope is stored in the object with the object key suffixed
        #   by this string.
        attr_reader :instruction_file_suffix

        # @return [Symbol, nil] Optional commitment policy for V2 to V3 migration.
        #   When set to :forbid_encrypt_allow_decrypt, explicitly indicates
        #   maintaining V2 encryption behavior while preparing for migration.
        attr_reader :commitment_policy

        # Uploads an object to Amazon S3, encrypting data client-side.
        # See {S3::Client#put_object} for documentation on accepted
        # request parameters.
        # @option params [Hash] :kms_encryption_context Additional encryption
        #   context to use with KMS.  Applies only when KMS is used. In order
        #   to decrypt the object you will need to provide the identical
        #   :kms_encryption_context to `get_object`.
        # @option (see S3::Client#put_object)
        # @return (see S3::Client#put_object)
        # @see S3::Client#put_object
        def put_object(params = {})
          kms_encryption_context = params.delete(:kms_encryption_context)
          req = @client.build_request(:put_object, params)
          req.handlers.add(EncryptHandler, priority: 95)
          req.context[:encryption] = {
            cipher_provider: @cipher_provider,
            envelope_location: @envelope_location,
            instruction_file_suffix: @instruction_file_suffix,
            kms_encryption_context: kms_encryption_context
          }
          Aws::Plugins::UserAgent.metric('S3_CRYPTO_V2') do
            req.send_request
          end
        end

        # 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
        #   is stored in the object metadata. Defaults to
        #   {#instruction_file_suffix}.
        # @option params [Hash] :kms_encryption_context Additional encryption
        #   context to use with KMS.  Applies only when KMS is used.
        # @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
        # @note The `:range` request parameter is not supported.
        def get_object(params = {}, &block)
          if params[:range]
            raise NotImplementedError, '#get_object with :range not supported'
          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,
            v3_cipher_provider: @v3_cipher_provider,
            envelope_location: envelope_location,
            instruction_file_suffix: instruction_file_suffix,
            kms_encryption_context: kms_encryption_context,
            kms_allow_decrypt_with_any_cmk: kms_any_cmk_mode,
            security_profile: security_profile
          }
          Aws::Plugins::UserAgent.metric('S3_CRYPTO_V2') do
            req.send_request(target: block)
          end
        end

        private

        def build_cipher_provider(options)
          if options[:kms_key_id]
            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,
              key_wrap_schema: options[:key_wrap_schema],
              content_encryption_schema: options[:content_encryption_schema]
            )
          end
        end

        def build_v3_cipher_provider_for_decrypt(options)
          if options[:kms_key_id]
            Aws::S3::EncryptionV3::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
            # Create V3 key provider explicitly for proper namespace consistency
            key_provider = if options[:key_provider]
              options[:key_provider]
            elsif options[:encryption_key]
              Aws::S3::EncryptionV3::DefaultKeyProvider.new(options)
            else
              msg = 'you must pass a :kms_key_id, :key_provider, or :encryption_key'
              raise ArgumentError, msg
            end
            Aws::S3::EncryptionV3::DefaultCipherProvider.new(
              key_provider: key_provider,
              key_wrap_schema: options[:key_wrap_schema],
              content_encryption_schema: options[:content_encryption_schema]
            )
          end
        end

        # 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
            options.delete(:kms_key_id)
            options.delete(:kms_client)
            options.delete(:key_provider)
            options.delete(:encryption_key)
            options.delete(:envelope_location)
            options.delete(:instruction_file_suffix)
            options.delete(:commitment_policy)
            REQUIRED_PARAMS.each { |p| options.delete(p) }
            S3::Client.new(options)
          end
        end

        def kms_client(options)
          options[:kms_client] || (@kms_client ||=
            KMS::Client.new(
              region: @client.config.region,
              credentials: @client.config.credentials,
              )
          )
        end

        def extract_key_provider(options)
          if options[:key_provider]
            options[:key_provider]
          elsif options[:encryption_key]
            DefaultKeyProvider.new(options)
          else
            msg = 'you must pass a :kms_key_id, :key_provider, or :encryption_key'
            raise ArgumentError, msg
          end
        end

        def envelope_options(params)
          location = params.delete(:envelope_location) || @envelope_location
          suffix = params.delete(:instruction_file_suffix)
          if suffix
            [:instruction_file, suffix]
          else
            [location, @instruction_file_suffix]
          end
        end

        def extract_location(options)
          location = options[:envelope_location] || :metadata
          if [:metadata, :instruction_file].include?(location)
            location
          else
            msg = ':envelope_location must be :metadata or :instruction_file '\
                  "got #{location.inspect}"
            raise ArgumentError, msg
          end
        end

        def extract_suffix(options)
          suffix = options[:instruction_file_suffix] || '.instruction'
          if suffix.is_a? String
            suffix
          else
            msg = ':instruction_file_suffix must be a String'
            raise ArgumentError, msg
          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

        def extract_commitment_policy(options)
          validate_commitment_policy(options[:commitment_policy])
        end

        def validate_commitment_policy(commitment_policy)
          return nil if commitment_policy.nil?

          unless SUPPORTED_COMMITMENT_POLICIES.include? commitment_policy
            raise ArgumentError, "Unsupported commitment policy: :#{commitment_policy}. " \
            "The V2 client only supports :forbid_encrypt_allow_decrypt for migration purposes. " \
            "For migration guidance, see: https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/s3-encryption-migration-v2-v3.html"
          end
          commitment_policy
        end
      end
    end
  end
end

##= ../specification/s3-encryption/data-format/content-metadata.md#v1-v2-shared
##= type=exception
##= reason=This has never been supported in Ruby
##% This string MAY be encoded by the esoteric double-encoding scheme used by the S3 web server.
