aws-sdk-s3 1.68.1 → 1.69.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfdbbed3a219f8690462fbca974111e863bbb4b3a3677648cf77dec94af963e9
-  data.tar.gz: 285b62f651038d1bf38e9fc156ec48d78b6aedd21f869455cfdb942aad7d817c
+  metadata.gz: 42108655e1496a1ce6df9db9b19ea1733e1c2d3710b70d8a27bb6c8b562fb307
+  data.tar.gz: 2b759d809937dc65075c1e193ce71972de3ce592ac7d6d01d782e1eb401e6b1e
 SHA512:
-  metadata.gz: aaed81549dabc75fd9415706924178884c1a9b2d3cc0c8325be4540c28301dd45d6d376ba6fc75bba28f705764af6916b984818d5c2df0d360884db429578b31
-  data.tar.gz: 20bc2cf996bcc241fefe8beba3bb6e30d7f5678e764c23c16a05f00e91c47be098290d85b3fe48a87bdb1edf27b35ab5e632545a210e2c81b801aed682e01641
+  metadata.gz: d0342f210f9a406650291b5cc4a27315d39c142d042609362bc16b3ef20eafa2915243a7f72dcd3a84a81bcdc0e1209f76b440cddf3acd88dc62ce66cc6f67fb
+  data.tar.gz: e3090d0ea9210596cb6eaa93b95ad43fb8784de81b249ebe8e8db33fb97763e281192f593a0f07bf224fa820ec5d0ea5f225368d9e396982f10a9c3e8a528f91

data/lib/aws-sdk-s3.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:
@@ -66,6 +68,6 @@ require_relative 'aws-sdk-s3/event_streams'
 # @service
 module Aws::S3
 
-  GEM_VERSION = '1.68.1'
+  GEM_VERSION = '1.69.0'
 
 end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'thread'
 
 module Aws

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:
@@ -11668,7 +11670,7 @@ module Aws::S3
         params: params,
         config: config)
       context[:gem_name] = 'aws-sdk-s3'
-      context[:gem_version] = '1.68.1'
+      context[:gem_version] = '1.69.0'
       Seahorse::Client::Request.new(handlers, context)
     end
 

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:

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

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 # utility classes
 require 'aws-sdk-s3/bucket_region_cache'
 require 'aws-sdk-s3/encryption'
+require 'aws-sdk-s3/encryption_v2'
 require 'aws-sdk-s3/file_part'
 require 'aws-sdk-s3/file_uploader'
 require 'aws-sdk-s3/file_downloader'

data/lib/aws-sdk-s3/customizations/bucket.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'uri'
 
 module Aws

data/lib/aws-sdk-s3/customizations/multipart_upload.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Aws
   module S3
     class MultipartUpload

data/lib/aws-sdk-s3/customizations/object.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Aws
   module S3
     class Object

data/lib/aws-sdk-s3/customizations/object_summary.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Aws
   module S3
     class ObjectSummary

data/lib/aws-sdk-s3/customizations/types/list_object_versions_output.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Aws::S3::Types::ListObjectVersionsOutput
 
   # TODO : Remove this customization once the resource code

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'aws-sdk-s3/encryption/client'
 require 'aws-sdk-s3/encryption/decrypt_handler'
 require 'aws-sdk-s3/encryption/default_cipher_provider'

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 
 module Aws

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'base64'
 
 module Aws
@@ -30,6 +32,7 @@ module Aws
 
         def call(context)
           attach_http_event_listeners(context)
+          apply_cse_user_agent(context)
           @handler.call(context)
         end
 
@@ -173,6 +176,14 @@ module Aws
           context.http_response.headers['x-amz-meta-x-amz-tag-len']
         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'
+          end
+        end
+
       end
     end
   end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'base64'
 
 module Aws

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Aws
   module S3
     module Encryption

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'base64'
 
 module Aws
@@ -10,6 +12,7 @@ module Aws
           envelope, cipher = context[:encryption][:cipher_provider].encryption_cipher
           apply_encryption_envelope(context, envelope, cipher)
           apply_encryption_cipher(context, cipher)
+          apply_cse_user_agent(context)
           @handler.call(context)
         end
 
@@ -44,6 +47,14 @@ module Aws
           end
         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'
+          end
+        end
+
       end
     end
   end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Aws
   module S3
     module Encryption

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Aws
   module S3
     module Encryption

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Aws
   module S3
     module Encryption
@@ -8,7 +10,8 @@ module Aws
         # @param [IO#write] io An IO-like object that responds to `#write`.
         def initialize(cipher, io)
           @cipher = cipher.clone
-          @io = io
+          # Ensure that IO is reset between retries
+          @io = io.tap { |io| io.truncate(0) if io.respond_to?(:truncate) }
         end
 
         # @return [#write]
@@ -23,6 +26,10 @@ module Aws
           @io.write(@cipher.final)
         end
 
+        def size
+          @io.size
+        end
+
       end
     end
   end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'stringio'
 require 'tempfile'
 

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Aws
   module S3
     module Encryption

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'base64'
 
 module Aws

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'base64'
 
 module Aws

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'openssl'
 
 module Aws

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

@@ -0,0 +1,378 @@
+require 'forwardable'
+
+module Aws
+  module S3
+
+    # 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.
+    #
+    # 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)
+    #
+    #     # 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 ..."
+    #
+    # ## Keys
+    #
+    # For client-side encryption to work, you must provide one of the following:
+    #
+    # * An encryption key
+    # * A {KeyProvider}
+    # * 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
+    #
+    #     s3 = Aws::S3::EncryptionV2::Client.new(encryption_key: key)
+    #
+    # ### 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 to an AWS Key Management Service (KMS) key,
+    # 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,
+    #     )
+    #
+    # ## 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.load(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)
+    #
+    # ## 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
+    #     )
+    #
+    # 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 provide one of the following
+        # 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`.
+        #
+        # @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 [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.
+        #
+        def initialize(options = {})
+          @client = extract_client(options)
+          @cipher_provider = cipher_provider(options)
+          @envelope_location = extract_location(options)
+          @instruction_file_suffix = extract_suffix(options)
+        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<: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
+
+        # Uploads an object to Amazon S3, encrypting data client-side.
+        # See {S3::Client#put_object} for documentation on accepted
+        # request parameters.
+        # @option (see S3::Client#put_object)
+        # @return (see S3::Client#put_object)
+        # @see S3::Client#put_object
+        def put_object(params = {})
+          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,
+          }
+          req.send_request
+        end
+
+        # Gets an object from Amazon S3, decrypting  data locally.
+        # See {S3::Client#get_object} for documentation on accepted
+        # request parameters.
+        # @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 [String] :instruction_file_suffix
+        # @option (see S3::Client#get_object)
+        # @return (see S3::Client#get_object)
+        # @see S3::Client#get_object
+        # @note The `:range` request parameter is not yet 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)
+          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,
+          }
+          req.send_request(target: block)
+        end
+
+        private
+
+        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)
+            S3::Client.new(options)
+          end
+        end
+
+        def kms_client(options)
+          options[:kms_client] || begin
+            KMS::Client.new(
+              region: @client.config.region,
+              credentials: @client.config.credentials,
+            )
+          end
+        end
+
+        def cipher_provider(options)
+          if options[:kms_key_id]
+            KmsCipherProvider.new(
+              kms_key_id: options[:kms_key_id],
+              kms_client: kms_client(options),
+            )
+          else
+            @key_provider = extract_key_provider(options)
+            DefaultCipherProvider.new(key_provider: @key_provider)
+          end
+        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
+
+      end
+    end
+  end
+end