aws-sdk-resources 2.0.14.pre → 2.0.15.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7178a784082813d4c136a0a3368a3544bdb14318
-  data.tar.gz: 49c521f7cfd5386e5d6491efc1e463c71352fb47
+  metadata.gz: f052a7ea17d6dae941c7488668075d7faecf9767
+  data.tar.gz: cae90c630414ec0552c9b8e4df95449222d048e7
 SHA512:
-  metadata.gz: 36866064d42e993de02eb9a1949465cd7585322cb2be6ca2a5b4284e9f0b810454f878568c417832d53c82ba8a39921e740a033a86e1f90d650ecfeeab53ce7f
-  data.tar.gz: 8f14831679ce01d83360f2116ff1942f1ecf61065ce175dfa72266172a158860421c984457a3d8906e8514945b95ee3685c844cf3a195aeccd916594cb999c3c
+  metadata.gz: bc04753ba36090c1c4f521b2c2648d1bfd0f8cfa3071c15cd2ae21ec828cda120aa31c08dfd72941a20e71c12140773ce15fd8b124eb32e2b8e5f1e049a69212
+  data.tar.gz: 901efaa0baa5c3f8e52871c4ec57c963400c0cf1ebed22ec8f59d34f2cc2fe2d5d4cbfde9fc34af7da5639656e0da834a78723ce3efca06a8c5c16484c71c824

data/lib/aws-sdk-resources/services/s3.rb

@@ -6,6 +6,7 @@ module Aws
     require 'aws-sdk-resources/services/s3/multipart_upload'
     require 'aws-sdk-resources/services/s3/public_url'
 
+    autoload :Encryption, 'aws-sdk-resources/services/s3/encryption'
     autoload :FilePart, 'aws-sdk-resources/services/s3/file_part'
     autoload :FileUploader, 'aws-sdk-resources/services/s3/file_uploader'
     autoload :MultipartFileUploader, 'aws-sdk-resources/services/s3/multipart_file_uploader'

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

@@ -0,0 +1,18 @@
+module Aws
+  module S3
+    module Encryption
+
+      autoload :Client, 'aws-sdk-resources/services/s3/encryption/client'
+      autoload :DecryptHandler, 'aws-sdk-resources/services/s3/encryption/decrypt_handler'
+      autoload :DefaultKeyProvider, 'aws-sdk-resources/services/s3/encryption/default_key_provider'
+      autoload :EncryptHandler, 'aws-sdk-resources/services/s3/encryption/encrypt_handler'
+      autoload :Errors, 'aws-sdk-resources/services/s3/encryption/errors'
+      autoload :IOEncrypter, 'aws-sdk-resources/services/s3/encryption/io_encrypter'
+      autoload :IODecrypter, 'aws-sdk-resources/services/s3/encryption/io_decrypter'
+      autoload :KeyProvider, 'aws-sdk-resources/services/s3/encryption/key_provider'
+      autoload :Materials, 'aws-sdk-resources/services/s3/encryption/materials'
+      autoload :Utils, 'aws-sdk-resources/services/s3/encryption/utils'
+
+    end
+  end
+end

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

@@ -0,0 +1,276 @@
+module Aws
+  module S3
+
+    # Provides an encryption client that encrypts and decrypts data client-side,
+    # storing the encrypted data in Amazon S3.
+    #
+    # 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 loose you encrption keys, you will not be able to
+    # un-encrypt 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 jut 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::Encryption::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 an encryption key:
+    #
+    #     key = OpenSSL::Cipher.new("AES-256-ECB").random_key # symmetric key
+    #     key = OpenSSL::PKey::RSA.new(1024) # asymmetric key pair
+    #
+    #     s3 = Aws::S3::Encryption::Client.new(encryption_key: key)
+    #
+    # Alternatively, you can use a {KeyProvider}. A key provider makes
+    # it easy to work with multiple keys and simplifies key rotation.
+    #
+    # ### Key Provider
+    #
+    # 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::Encryption::Materials.new(
+    #           key: @keys[default_key_name],
+    #           description: MultiJson.dump(key: default_key_name),
+    #         )
+    #       end
+    #
+    #       attr_reader :encryption_materials
+    #
+    #       def key_for(matdesc)
+    #         key_name = MultiJson.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::Encryption::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::Encryption::Client.new(
+    #       key_provider: ...,
+    #       envelope_location: :metadata,
+    #     )
+    #
+    #     # store envelope in a separate object
+    #     s3 = Aws::S3::Encryption::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 Encryption
+
+      class Client
+
+        # Creates a new encryption client. You must provide on of the following
+        # options:
+        #
+        # * `:key_provider`
+        # * `:encryption_key`
+        #
+        # @option opitons [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 [#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 [OpenSSL::PKey::RSA, String] :encryption_key The master
+        #   key to use for encrypting/decrypting all objects.
+        #
+        # @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 seperate 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.
+        #
+        def initialize(options = {})
+          @client = options[:client] || S3::Client.new
+          @key_provider = extract_key_provider(options)
+          @envelope_location = extract_location(options)
+          @instruction_file_suffix = extract_suffix(options)
+        end
+
+        # @return [S3::Client]
+        attr_reader :client
+
+        # @return [KeyProvider]
+        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
+
+        # Calls {S3::Client#put_object}. The `:body` option will be encrypted
+        # client-side before sending data to Amazon S3.
+        # @see S3::Client#put_object
+        def put_object(options = {})
+          req = @client.build_request(:put_object, options)
+          req.handlers.add(EncryptHandler, priority: 95)
+          req.context[:encryption] = {
+            materials: @key_provider.encryption_materials,
+            envelope_location: @envelope_location,
+            instruction_file_suffix: @instruction_file_suffix,
+          }
+          req.send_request
+        end
+
+        # Performs an `#get_object` request on the `#config.client`. The
+        # response body is decrypted as it is read from the HTTP response
+        # socket. See {Client#get_object} for documentation on valid
+        # options.
+        def get_object(options = {})
+          if options[:range]
+            raise NotImplementedError, '#get_object with :range not supported yet'
+          end
+
+          location = options.delete(:envelope_location) || @envelope_location
+          suffix = options.delete(:instruction_file_suffix) || @instruction_file_suffix
+
+          req = @client.build_request(:get_object, options)
+          req.handlers.add(DecryptHandler)
+          req.context[:encryption] = {
+            key_provider: @key_provider,
+            envelope_location: location,
+            instruction_file_suffix: suffix,
+          }
+          req.send_request
+        end
+
+        private
+
+        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 :key_provider or :encryption_key"
+            raise ArgumentError, msg
+          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 "
+            msg << "got #{location.inspect}"
+            raise ArgumentError, msg
+          end
+        end
+
+        def extract_suffix(options)
+          suffix = options[:instruction_file_suffix] || '.instruction'
+          if String === suffix
+            suffix
+          else
+            msg = ":instruction_file_suffix must be a String"
+            raise ArgumentError, msg
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/services/s3/encryption/config.rb

@@ -0,0 +1,65 @@
+module Aws
+  module S3
+    module Encryption
+      class Config < Struct.new(
+        :client,
+        :key_provider,
+        :materials_description,
+        :materials_location,
+        :instruction_file_suffix)
+
+        # @api private
+        DEFAULTS = {
+          client: lambda { S3::Client.new },
+          key_provider: lambda {
+            msg = "must specify an :encryption_key or :key_provider"
+            raise ArgumentError, msg
+          },
+          materials_description: '{}',
+          materials_location: :metadata,
+          instruction_file_suffix: '.instruction',
+        }
+
+        def encryption_key= master_key
+          self[:key_provider] = DefaultKeyProvider.new(master_key)
+        end
+
+        # @param [Symbol] location :metadata Must be one of
+        #   the following values:
+        #   * :metadata
+        #   * :instruction_file
+        def materials_location= location
+          unless [:metadata, :instruction_file].include?(location)
+            msg = ":materials_location must be :metadata or :instruction_file "
+            msg << "got #{location.inspect}"
+            raise ArgumentError, msg
+          end
+          super
+        end
+
+        class << self
+
+          def build(options)
+            config = Config.new
+            options.each do |opt_name, opt_value|
+              config.send("#{opt_name}=", opt_value)
+            end
+            apply_defaults(config)
+            config
+          end
+
+          private
+
+          def apply_defaults(config)
+            DEFAULTS.each do |key, value|
+              if config[key].nil?
+                config[key] = value.is_a?(Proc) ? value.call : value
+              end
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+require 'base64'
+
+module Aws
+  module S3
+    module Encryption
+      # @api private
+      class DecryptHandler < Seahorse::Client::Handler
+
+        def call(context)
+          attach_http_event_listeners(context)
+          @handler.call(context)
+        end
+
+        private
+
+        def attach_http_event_listeners(context)
+          context.http_response.on_headers(200) do
+            cipher = decryption_cipher(context)
+            body = context.http_response.body
+            context.http_response.body = IODecrypter.new(cipher, body)
+          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
+            if context.http_response.body.is_a?(IODecrypter)
+              context.http_response.body = context.http_response.body.io
+            end
+          end
+        end
+
+        def decryption_cipher(context)
+          if envelope = get_encryption_envelope(context)
+            key_provider = context[:encryption][:key_provider]
+            key = key_provider.key_for(envelope['x-amz-matdesc'])
+            envelope_key = Utils.decrypt(key, decode64(envelope['x-amz-key']))
+            envelope_iv = decode64(envelope['x-amz-iv'])
+            Utils.aes_decryption_cipher(:CBC, envelope_key, envelope_iv)
+          else
+            raise Errors::DecryptionError, "unable to locate encyrption envelope"
+          end
+        end
+
+        def get_encryption_envelope(context)
+          if context[:encryption][:envelope_location] == :metadata
+            envelope_from_metadata(context) || envelope_from_instr_file(context)
+          else
+            envelope_from_instr_file(context) || envelope_from_metadata(context)
+          end
+        end
+
+        def envelope_from_metadata(context)
+          keys = %w(x-amz-key x-amz-iv x-amz-matdesc)
+          envelope = keys.each.with_object({}) do |key, hash|
+            if value = context.http_response.headers["x-amz-meta-#{key}"]
+              hash[key] = value
+            end
+          end
+          envelope.keys == keys ? envelope : nil
+        end
+
+        def envelope_from_instr_file(context)
+          suffix = context[:encryption][:instruction_file_suffix]
+          MultiJson.load(context.client.get_object(
+            bucket: context.params[:bucket],
+            key: context.params[:key] + suffix
+          ).body.read)
+        rescue S3::Errors::ServiceError, MultiJson::ParseError
+          nil
+        end
+
+        def decode64(str)
+          Base64.decode64(str)
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+module Aws
+  module S3
+    module Encryption
+
+      # 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 encyrption key.
+        def initialize(options = {})
+          @encryption_materials = Materials.new(
+            key: options[:encryption_key],
+            description: options[:materials_description] || '{}'
+          )
+        end
+
+        # @return [Materials]
+        def encryption_materials
+          @encryption_materials
+        end
+
+        # @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-resources/services/s3/encryption/encrypt_handler.rb

@@ -0,0 +1,71 @@
+require 'base64'
+
+module Aws
+  module S3
+    module Encryption
+      # @api private
+      class EncryptHandler < Seahorse::Client::Handler
+
+        def call(context)
+          cipher = Utils.aes_encryption_cipher(:CBC)
+          context[:encryption][:cipher] = cipher
+          envelope = {
+            'x-amz-key' => encode64(encrypt(context, envelope_key(cipher))),
+            'x-amz-iv' => encode64(envelope_iv(cipher)),
+            'x-amz-matdesc' => context[:encryption][:materials].description,
+          }
+          apply_encryption_envelope(context, envelope)
+          apply_encryption_cipher(context, cipher)
+          @handler.call(context)
+        end
+
+        private
+
+        def apply_encryption_envelope(context, envelope)
+          if context[:encryption][:envelope_location] == :metadata
+            context.params[:metadata] ||= {}
+            context.params[:metadata].update(envelope)
+          else # :instruction_file
+            suffix = context[:encryption][:instruction_file_suffix]
+            context.client.put_object(
+              bucket: context.params[:bucket],
+              key: context.params[:key] + suffix,
+              body: MultiJson.dump(envelope)
+            )
+          end
+        end
+
+        def apply_encryption_cipher(context, cipher)
+          io = context.params[:body] || ''
+          io = StringIO.new(io) if String === io
+          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
+          end
+          context.http_response.on_headers do
+            context.params[:body].close
+          end
+        end
+
+        def envelope_key(cipher)
+          cipher.key = cipher.random_key
+        end
+
+        def envelope_iv(cipher)
+          cipher.iv = cipher.random_iv
+        end
+
+        def encode64(str)
+          Base64.encode64(str).split("\n") * ""
+        end
+
+        def encrypt(context, data)
+          Utils.encrypt(context[:encryption][:materials].key, data)
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Aws
+  module S3
+    module Encryption
+      module Errors
+
+        class DecryptionError < RuntimeError; end
+
+        class EncryptionError < RuntimeError; end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+module Aws
+  module S3
+    module Encryption
+      # @api private
+      class IODecrypter
+
+        # @param [OpenSSL::Cipher] cipher
+        # @param [#write] io An IO-like object that responds to {#write}.
+        def initialize(cipher, io)
+          @orig_cipher = cipher.clone
+          @cipher = cipher.clone
+          @io = io
+          reset_cipher
+        end
+
+        # @return [#write]
+        attr_reader :io
+
+        def write(chunk)
+          @io.write(@cipher.update(chunk))
+        end
+
+        def finalize
+          @io.write(@cipher.final)
+        end
+
+        private
+
+        def reset_cipher
+          @cipher = @orig_cipher.clone
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+require 'stringio'
+require 'tempfile'
+
+module Aws
+  module S3
+    module Encryption
+
+      # Provides an IO wrapper encrpyting a stream of data.
+      # It is possible to use this same object for decrypting. You must
+      # initialize it with a decryptiion cipher in that case and the
+      # IO object must contain cipher text instead of plain text.
+      # @api private
+      class IOEncrypter
+
+        # @api private
+        ONE_MEGABYTE = 1024 * 1024
+
+        def initialize(cipher, io)
+          @encrypted = io.size <= ONE_MEGABYTE ?
+            encrypt_to_stringio(cipher, io.read) :
+            encrypt_to_tempfile(cipher, io)
+          @size = @encrypted.size
+        end
+
+        # @return [Integer]
+        attr_reader :size
+
+        def read(bytes =  nil, output_buffer = nil)
+          if Tempfile === @encrypted && @encrypted.closed?
+            @encrypted.open
+            @encrypted.binmode
+          end
+          @encrypted.read(bytes, output_buffer)
+        end
+
+        def rewind
+          @encrypted.rewind
+        end
+
+        # @api private
+        def close
+          @encrypted.close if Tempfile === @encrypted
+        end
+
+        private
+
+        def encrypt_to_stringio(cipher, plain_text)
+          if plain_text.empty?
+            StringIO.new(cipher.final)
+          else
+            StringIO.new(cipher.update(plain_text) + cipher.final)
+          end
+        end
+
+        def encrypt_to_tempfile(cipher, io)
+          encrypted = Tempfile.new(self.object_id.to_s)
+          encrypted.binmode
+          while chunk = io.read(ONE_MEGABYTE)
+            encrypted.write(cipher.update(chunk))
+          end
+          encrypted.write(cipher.final)
+          encrypted.rewind
+          encrypted
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Aws
+  module S3
+    module Encryption
+
+      # This module defines the interface required for a {Client#key_provider}.
+      # A key provider is any object that:
+      #
+      # * Responds to {#encryption_materials} with an {Materials} object.
+      #
+      # * Responds to {#key_for}, receiving a JSON document String,
+      #   returning an ecryption key. The returned encryption key
+      #   must be one of:
+      #
+      #   * `OpenSSL::PKey::RSA` - for asymmetric encryption
+      #   * `String` - 32, 24, or 16 bytes long, for symmetric encryption
+      #
+      module KeyProvider
+
+        # @return [Materials]
+        def encryption_materials; end
+
+        # @param [String<JSON>] materials_description
+        # @return [OpenSSL::PKey::RSA, String] encryption_key
+        def key_for(materials_description); end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+require 'base64'
+
+module Aws
+  module S3
+    module Encryption
+      class Materials
+
+        # @option options [required, OpenSSL::PKey::RSA, String] :encryption_key
+        #   The master key to use for encrypting/decrypting all objects.
+        #
+        # @option options [String<JSON>] :materials_description ('{}')
+        #   The encryption materials description. This is must be
+        #   a JSON document string.
+        #
+        # @option options [Symbol] :materials_location (:metadata) Where to
+        #   store the envelope encryption keys. This must be one of
+        #   the following values:
+        #
+        #   * `:metadata`
+        #   * `:instruction_file`
+        #
+        # @option options [String] :instruction_file_suffix ('.instruction')
+        #
+        def initialize(options = {})
+          @key = validate_key(options[:key])
+          @description = validate_desc(options[:description])
+        end
+
+        # @return [OpenSSL::PKey::RSA, String]
+        attr_reader :key
+
+        # @return [String<JSON>]
+        attr_reader :description
+
+        private
+
+        def validate_key(key)
+          case key
+          when OpenSSL::PKey::RSA then key
+          when String
+            if [32, 24, 16].include?(key.bytesize)
+              key
+            else
+              msg = "invalid key, symmetric key required to be 16, 24, or "
+              msg << "32 bytes in length, saw length 31"
+              raise ArgumentError, msg
+            end
+          else
+            msg = "invalid encryption key, expected an OpenSSL::PKey::RSA key "
+            msg << "(for asymmetric encryption) or a String (for symmetric "
+            msg << "encryption)."
+            raise ArgumentError, msg
+          end
+        end
+
+        def validate_desc(description)
+          MultiJson.load(description)
+          description
+        rescue MultiJson::ParseError
+          msg = "expected description to be a valid JSON document string"
+          raise ArgumentError, msg
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+require 'openssl'
+
+module Aws
+  module S3
+    module Encryption
+      # @api private
+      module Utils
+
+        UNSAFE_MSG = "unsafe encryption, data is longer than key length"
+
+        class << self
+
+          def encrypt(key, data)
+            case key
+            when OpenSSL::PKey::RSA # asymmetric encryption
+              warn(UNSAFE_MSG) if key.public_key.n.num_bits < cipher_size(data)
+              key.public_encrypt(data)
+            when String # symmetric encryption
+              warn(UNSAFE_MSG) if cipher_size(key) < cipher_size(data)
+              cipher = aes_encryption_cipher(:ECB, key)
+              cipher.update(data) + cipher.final
+            end
+          end
+
+          def decrypt(key, data)
+            rsa = OpenSSL::PKey::RSA
+            begin
+              case key
+              when OpenSSL::PKey::RSA # asymmetric decryption
+                key.private_decrypt(data)
+              when String # symmetric Decryption
+                cipher = aes_cipher(:decrypt, :ECB, key, nil)
+                cipher.update(data) + cipher.final
+              end
+            rescue OpenSSL::Cipher::CipherError
+              msg = 'decryption failed, possible incorrect key'
+              raise Errors::DecryptionError, msg
+            end
+          end
+
+          # @param [String] block_mode "CBC" or "ECB"
+          # @param [OpenSSL::PKey::RSA, String, nil] key
+          # @param [String, nil] iv The initialization vector
+          def aes_encryption_cipher(block_mode, key = nil, iv = nil)
+            aes_cipher(:encrypt, block_mode, key, iv)
+          end
+
+          # @param [String] block_mode "CBC" or "ECB"
+          # @param [OpenSSL::PKey::RSA, String, nil] key
+          # @param [String, nil] iv The initialization vector
+          def aes_decryption_cipher(block_mode, key = nil, iv = nil)
+            aes_cipher(:decrypt, block_mode, key, iv)
+          end
+
+          # @param [String] mode "encrypt" or "decrypt"
+          # @param [String] block_mode "CBC" or "ECB"
+          # @param [OpenSSL::PKey::RSA, String, nil] key
+          # @param [String, nil] iv The initialization vector
+          def aes_cipher(mode, block_mode, key, iv)
+            cipher = key ?
+              OpenSSL::Cipher.new("AES-#{cipher_size(key)}-#{block_mode}") :
+              OpenSSL::Cipher.new("AES-256-#{block_mode}")
+            cipher.send(mode) # encrypt or decrypt
+            cipher.key = key if key
+            cipher.iv = iv if iv
+            cipher
+          end
+
+          # @param [String] key
+          # @return [Integer]
+          # @raise ArgumentError
+          def cipher_size(key)
+            key.bytesize * 8
+          end
+
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-sdk-resources
 version: !ruby/object:Gem::Version
-  version: 2.0.14.pre
+  version: 2.0.15.pre
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-12 00:00:00.000000000 Z
+date: 2014-12-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-core
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.14
+        version: 2.0.15
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.14
+        version: 2.0.15
 description: Provides resource-oriented abstractions for AWS.
 email: 
 executables: []
@@ -53,6 +53,18 @@ files:
 - lib/aws-sdk-resources/services/ec2/instance.rb
 - lib/aws-sdk-resources/services/ec2.rb
 - lib/aws-sdk-resources/services/s3/bucket.rb
+- lib/aws-sdk-resources/services/s3/encryption/client.rb
+- lib/aws-sdk-resources/services/s3/encryption/config.rb
+- lib/aws-sdk-resources/services/s3/encryption/decrypt_handler.rb
+- lib/aws-sdk-resources/services/s3/encryption/default_key_provider.rb
+- lib/aws-sdk-resources/services/s3/encryption/encrypt_handler.rb
+- lib/aws-sdk-resources/services/s3/encryption/errors.rb
+- lib/aws-sdk-resources/services/s3/encryption/io_decrypter.rb
+- lib/aws-sdk-resources/services/s3/encryption/io_encrypter.rb
+- lib/aws-sdk-resources/services/s3/encryption/key_provider.rb
+- lib/aws-sdk-resources/services/s3/encryption/materials.rb
+- lib/aws-sdk-resources/services/s3/encryption/utils.rb
+- lib/aws-sdk-resources/services/s3/encryption.rb
 - lib/aws-sdk-resources/services/s3/file_part.rb
 - lib/aws-sdk-resources/services/s3/file_uploader.rb
 - lib/aws-sdk-resources/services/s3/multipart_file_uploader.rb