symmetric-encryption 4.0.1 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8b4f45cc7b6dca91b1eb5d8eb5df044485d0a484f93472ce38fee62559453e8
-  data.tar.gz: 973376b8363032b2a71aaf840a3012cf7485d7f6b16f2ea1ebf20f622eaf56f0
+  metadata.gz: 825c28cf5b38d4cf22d26f4ed8196bbf1085ee0e09b372ab3c30aa055238902f
+  data.tar.gz: de736c34beb30c50e9316f0f85cade71b022caac4fe4ca94cc61c94d0c8fe1aa
 SHA512:
-  metadata.gz: ae3695e636ea98bcbfe489187e26244dee6116257afdf4383a234359c201974024d3180d1ea1851edbc1798343ce1ab862fea20691a01f8eb7993b58a7206921
-  data.tar.gz: cbe308f3287c77c32996551b8f4ace32fd803e123e32f906ed21d65bf6d3823b19ce5459623a445a4ffd4bb1b33a0377558ad6604e98d61ae17b206d4cef1892
+  metadata.gz: 711727ec509464e8807f798f82c4944c25f37a2cd48ec190c93f4f0134437887c8355fedf199157727ffd7faaa1023146fa95946ee6f2f9ec8a648426ec68f60
+  data.tar.gz: 834ae0b58bd0ca3011b846a94709203ac648a6cd341c5f86f18c82fa4b4c9b16abfc400af9d3c7c0f0348b4127db7c425de56345738bfde0de5dae97666a4031

data/README.md

@@ -29,13 +29,6 @@ Checkout the sister project [Rocket Job](http://rocketjob.io): Ruby's missing ba
 
 Fully supports Symmetric Encryption to encrypt data in flight and at rest while running jobs in the background.
 
-## Supports
-
-Symmetric Encryption works with the following Ruby VMs:
-
-- Ruby 2.1 and higher.
-- JRuby 9.1 and higher.
-
 ## Upgrading to SymmetricEncryption V4
 
 Version 4 of Symmetric Encryption has completely adopted the Ruby keyword arguments on most API's where

data/lib/symmetric_encryption/cipher.rb

@@ -18,8 +18,8 @@ module SymmetricEncryption
                          encoding: :base64strict,
                          **config)
 
-      Key.migrate_config!(config)
-      key = Key.from_config(cipher_name: cipher_name, **config)
+      Keystore.migrate_config!(config)
+      key = Keystore.read_key(cipher_name: cipher_name, **config)
 
       Cipher.new(
         key:               key.key,
@@ -133,8 +133,10 @@ module SymmetricEncryption
     #       compression
     def encrypt(str, random_iv: false, compress: false, header: always_add_header)
       return if str.nil?
+
       str = str.to_s
       return str if str.empty?
+
       encrypted = binary_encrypt(str, random_iv: random_iv, compress: compress, header: header)
       encode(encrypted)
     end
@@ -161,6 +163,7 @@ module SymmetricEncryption
       return unless decoded
 
       return decoded if decoded.empty?
+
       decrypted = binary_decrypt(decoded)
 
       # Try to force result to UTF-8 encoding, but if it is not valid, force it back to Binary
@@ -178,6 +181,7 @@ module SymmetricEncryption
     # Returned string is UTF8 encoded except for encoding :none
     def encode(binary_string)
       return binary_string if binary_string.nil? || (binary_string == '')
+
       encoder.encode(binary_string)
     end
 
@@ -187,6 +191,7 @@ module SymmetricEncryption
     # Returned string is Binary encoded
     def decode(encoded_string)
       return encoded_string if encoded_string.nil? || (encoded_string == '')
+
       encoder.decode(encoded_string)
     end
 
@@ -243,6 +248,7 @@ module SymmetricEncryption
     # See #encrypt to encrypt and encode the result as a string.
     def binary_encrypt(str, random_iv: false, compress: false, header: always_add_header)
       return if str.nil?
+
       string = str.to_s
       return string if string.empty?
 
@@ -300,6 +306,7 @@ module SymmetricEncryption
     #   is automatically set to the same UTF-8 or Binary encoding
     def binary_decrypt(encrypted_string, header: Header.new)
       return if encrypted_string.nil?
+
       str = encrypted_string.to_s
       str.force_encoding(SymmetricEncryption::BINARY_ENCODING)
       return str if str.empty?
@@ -309,8 +316,8 @@ module SymmetricEncryption
 
       openssl_cipher = ::OpenSSL::Cipher.new(header.cipher_name || cipher_name)
       openssl_cipher.decrypt
-      openssl_cipher.key = header.key || @key
-      if (iv = header.iv || @iv)
+      openssl_cipher.key  = header.key || @key
+      if (iv              = header.iv || @iv)
         openssl_cipher.iv = iv
       end
       result = openssl_cipher.update(data)

data/lib/symmetric_encryption/cli.rb

@@ -6,7 +6,7 @@ module SymmetricEncryption
                 :decrypt, :random_password, :new_keys, :generate, :environment,
                 :keystore, :re_encrypt, :version, :output_file_name, :compress,
                 :environments, :cipher_name, :rolling_deploy, :rotate_keys, :rotate_kek, :prompt, :show_version,
-                :cleanup_keys, :activate_key, :migrate
+                :cleanup_keys, :activate_key, :migrate, :regions
 
     KEYSTORES = %i[heroku environment file].freeze
 
@@ -19,7 +19,7 @@ module SymmetricEncryption
       @environment      = ENV['SYMMETRIC_ENCRYPTION_ENV'] || ENV['RACK_ENV'] || ENV['RAILS_ENV'] || 'development'
       @config_file_path = File.expand_path(ENV['SYMMETRIC_ENCRYPTION_CONFIG'] || 'config/symmetric-encryption.yml')
       @app_name         = 'symmetric-encryption'
-      @key_path         = '/etc/symmetric-encryption'
+      @key_path         = '~/.symmetric-encryption'
       @cipher_name      = 'aes-256-cbc'
       @rolling_deploy   = false
       @prompt           = false
@@ -70,7 +70,7 @@ module SymmetricEncryption
     end
 
     def parser
-      @parser ||= OptionParser.new do |opts|
+      @parser     ||= OptionParser.new do |opts|
         opts.banner = <<~BANNER
           Symmetric Encryption v#{VERSION}
 
@@ -99,10 +99,14 @@ module SymmetricEncryption
           @prompt = true
         end
 
-        opts.on '-z', '--compress', 'Compress encrypted output file.' do
+        opts.on '-z', '--compress', 'Compress encrypted output file. [Default for encrypting files]' do
           @compress = true
         end
 
+        opts.on '-Z', '--no-compress', 'Does not compress the output file. [Default for encrypting strings]' do
+          @compress = false
+        end
+
         opts.on '-E', '--env ENVIRONMENT', "Environment to use in the config file. Default: SYMMETRIC_ENCRYPTION_ENV || RACK_ENV || RAILS_ENV || 'development'" do |environment|
           @environment = environment
         end
@@ -127,11 +131,15 @@ module SymmetricEncryption
           @generate = config
         end
 
-        opts.on '-s', '--keystore heroku|environment|file', 'Generate a new configuration file and encryption keys for every environment.' do |keystore|
+        opts.on '-s', '--keystore heroku|environment|file|aws', 'Which keystore to use during generation or re-encryption.' do |keystore|
           @keystore = (keystore || 'file').downcase.to_sym
         end
 
-        opts.on '-K', '--key-path KEY_PATH', 'Output path in which to write generated key files. Default: /etc/symmetric-encryption' do |path|
+        opts.on '-B', '--regions [us-east-1,us-east-2,us-west-1,us-west-2]', 'AWS KMS Regions to encrypt data key with.' do |regions|
+          @regions = regions.to_s.split(',').collect(&:strip) if regions
+        end
+
+        opts.on '-K', '--key-path KEY_PATH', 'Output path in which to write generated key files. Default: ~/.symmetric-encryption' do |path|
           @key_path = path
         end
 
@@ -197,26 +205,21 @@ module SymmetricEncryption
     end
 
     def generate_new_config
+      unless KEYSTORES.include?(keystore)
+        puts "Invalid keystore option: #{keystore}, must be one of #{KEYSTORES.join(', ')}"
+        exit(-3)
+      end
+
       config_file_does_not_exist!
       self.environments ||= %i[development test release production]
-      cfg               =
-        if keystore == :file
-          SymmetricEncryption::Keystore::File.new_config(
-            key_path:     key_path,
-            app_name:     app_name,
-            environments: environments,
-            cipher_name:  cipher_name
-          )
-        elsif %i[heroku environment].include?(keystore)
-          SymmetricEncryption::Keystore::Environment.new_config(
-            app_name:     app_name,
-            environments: environments,
-            cipher_name:  cipher_name
-          )
-        else
-          puts "Invalid keystore option: #{keystore}, must be one of #{KEYSTORES.join(', ')}"
-          exit(-3)
-        end
+      args                = {
+        app_name:     app_name,
+        environments: environments,
+        cipher_name:  cipher_name
+      }
+      args[:key_path]   = key_path if key_path
+      args[:regions]    = regions if regions && !regions.empty?
+      cfg               = Keystore.generate_data_keys(keystore, **args)
       Config.write_file(config_file_path, cfg)
       puts "New configuration file created at: #{config_file_path}"
     end
@@ -228,8 +231,13 @@ module SymmetricEncryption
     end
 
     def run_rotate_keys
+      if keystore && KEYSTORES.include?(keystore)
+        puts "Invalid keystore option: #{keystore}, must be one of #{KEYSTORES.join(', ')}"
+        exit(-3)
+      end
+
       config = Config.read_file(config_file_path)
-      SymmetricEncryption::Keystore.rotate_keys!(config, environments: environments || [], app_name: app_name, rolling_deploy: rolling_deploy)
+      SymmetricEncryption::Keystore.rotate_keys!(config, environments: environments || [], app_name: app_name, rolling_deploy: rolling_deploy, keystore: keystore)
       Config.write_file(config_file_path, config)
       puts "Existing configuration file updated with new keys: #{config_file_path}"
     end
@@ -246,7 +254,8 @@ module SymmetricEncryption
       config.each_pair do |env, cfg|
         next if environments && !environments.include?(env.to_sym)
         next unless ciphers = cfg[:ciphers]
-        highest = ciphers.max_by { |i| i[:version] }
+
+        highest             = ciphers.max_by { |i| i[:version] }
         ciphers.clear
         ciphers << highest
       end
@@ -260,7 +269,8 @@ module SymmetricEncryption
       config.each_pair do |env, cfg|
         next if environments && !environments.include?(env.to_sym)
         next unless ciphers = cfg[:ciphers]
-        highest = ciphers.max_by { |i| i[:version] }
+
+        highest             = ciphers.max_by { |i| i[:version] }
         ciphers.delete(highest)
         ciphers.unshift(highest)
       end
@@ -308,7 +318,7 @@ module SymmetricEncryption
 
         puts('Values do not match, please try again') if value1 != value2
       end
-
+      compress  = false if compress.nil?
       encrypted = SymmetricEncryption.cipher(version).encrypt(value1, compress: compress)
       output_file_name ? File.open(output_file_name, 'wb') { |f| f << encrypted } : puts("\n\nEncrypted: #{encrypted}\n\n")
     end
@@ -330,6 +340,7 @@ module SymmetricEncryption
     # Ensure that the config file does not already exist before generating a new one.
     def config_file_does_not_exist!
       return unless File.exist?(config_file_path)
+
       puts "\nConfiguration file already exists, please move or rename: #{config_file_path}\n\n"
       exit(-1)
     end

data/lib/symmetric_encryption/config.rb

@@ -53,8 +53,8 @@ module SymmetricEncryption
       env ||= defined?(Rails) ? Rails.env : ENV['RACK_ENV'] || ENV['RAILS_ENV'] || 'development'
 
       unless file_name
-        root      = defined?(Rails) ? Rails.root : '.'
-        file_name =
+        root          = defined?(Rails) ? Rails.root : '.'
+        file_name     =
           if (env_var = ENV['SYMMETRIC_ENCRYPTION_CONFIG'])
             File.expand_path(env_var)
           else
@@ -101,6 +101,7 @@ module SymmetricEncryption
         object
       end
     end
+
     private_class_method :deep_symbolize_keys
 
     # Iterate through the Hash symbolizing all keys.
@@ -119,28 +120,29 @@ module SymmetricEncryption
         object
       end
     end
+
     private_class_method :deep_stringify_keys
 
     # Migrate old configuration format for this environment
     def self.migrate_old_formats!(config)
       # Inline single cipher before :ciphers
       unless config.key?(:ciphers)
-        inline_cipher = {}
+        inline_cipher                               = {}
         config.keys.each { |key| inline_cipher[key] = config.delete(key) }
-        config[:ciphers] = [inline_cipher]
+        config[:ciphers]                            = [inline_cipher]
       end
 
       # Copy Old :private_rsa_key into each ciphers config
       # Cipher.from_config replaces it with the RSA Kek
       if config[:private_rsa_key]
-        private_rsa_key = config.delete(:private_rsa_key)
+        private_rsa_key                                           = config.delete(:private_rsa_key)
         config[:ciphers].each { |cipher| cipher[:private_rsa_key] = private_rsa_key }
       end
 
       # Old :cipher_name
       config[:ciphers].each do |cipher|
         if (old_key_name_cipher = cipher.delete(:cipher))
-          cipher[:cipher_name] = old_key_name_cipher
+          cipher[:cipher_name]  = old_key_name_cipher
         end
 
         # Only temporarily used during v4 Beta process
@@ -156,6 +158,7 @@ module SymmetricEncryption
       end
       config
     end
+
     private_class_method :migrate_old_formats!
   end
 end

data/lib/symmetric_encryption/encoder.rb

@@ -36,12 +36,14 @@ module SymmetricEncryption
     class Base64
       def encode(binary_string)
         return binary_string if binary_string.nil? || (binary_string == '')
+
         encoded_string = ::Base64.encode64(binary_string)
         encoded_string.force_encoding(SymmetricEncryption::UTF8_ENCODING)
       end
 
       def decode(encoded_string)
         return encoded_string if encoded_string.nil? || (encoded_string == '')
+
         decoded_string = ::Base64.decode64(encoded_string)
         decoded_string.force_encoding(SymmetricEncryption::BINARY_ENCODING)
       end
@@ -50,12 +52,14 @@ module SymmetricEncryption
     class Base64Strict
       def encode(binary_string)
         return binary_string if binary_string.nil? || (binary_string == '')
+
         encoded_string = ::Base64.strict_encode64(binary_string)
         encoded_string.force_encoding(SymmetricEncryption::UTF8_ENCODING)
       end
 
       def decode(encoded_string)
         return encoded_string if encoded_string.nil? || (encoded_string == '')
+
         decoded_string = ::Base64.decode64(encoded_string)
         decoded_string.force_encoding(SymmetricEncryption::BINARY_ENCODING)
       end
@@ -64,12 +68,14 @@ module SymmetricEncryption
     class Base16
       def encode(binary_string)
         return binary_string if binary_string.nil? || (binary_string == '')
+
         encoded_string = binary_string.to_s.unpack('H*').first
         encoded_string.force_encoding(SymmetricEncryption::UTF8_ENCODING)
       end
 
       def decode(encoded_string)
         return encoded_string if encoded_string.nil? || (encoded_string == '')
+
         decoded_string = [encoded_string].pack('H*')
         decoded_string.force_encoding(SymmetricEncryption::BINARY_ENCODING)
       end

data/lib/symmetric_encryption/extensions/mongoid/encrypted.rb

@@ -1,3 +1,4 @@
+require 'mongoid'
 # Add :encrypted option for Mongoid models
 #
 # Example:

data/lib/symmetric_encryption/generator.rb

@@ -12,7 +12,7 @@ module SymmetricEncryption
       raise(ArgumentError, "Invalid type: #{type.inspect}. Valid types: #{SymmetricEncryption::COERCION_TYPES.inspect}") unless SymmetricEncryption::COERCION_TYPES.include?(type)
 
       if model.const_defined?(:EncryptedAttributes, _search_ancestors = false)
-        mod = model.const_get(:EncryptedAttributes)
+        mod                                                           = model.const_get(:EncryptedAttributes)
       else
         mod = model.const_set(:EncryptedAttributes, Module.new)
         model.send(:include, mod)

data/lib/symmetric_encryption/header.rb

@@ -38,6 +38,7 @@ module SymmetricEncryption
     # Note: The encoding of the supplied buffer is forced to binary if not already binary
     def self.present?(buffer)
       return false if buffer.nil? || (buffer == '')
+
       buffer.force_encoding(SymmetricEncryption::BINARY_ENCODING)
       buffer.start_with?(MAGIC_HEADER)
     end
@@ -112,6 +113,7 @@ module SymmetricEncryption
     def parse!(buffer)
       offset = parse(buffer)
       return if offset.zero?
+
       buffer.slice!(0..offset - 1)
       buffer
     end
@@ -151,7 +153,7 @@ module SymmetricEncryption
 
       # Remove header and extract flags
       self.version = buffer.getbyte(offset)
-      offset       += 1
+      offset      += 1
 
       unless cipher
         raise(
@@ -160,7 +162,7 @@ module SymmetricEncryption
         )
       end
 
-      flags  = buffer.getbyte(offset)
+      flags   = buffer.getbyte(offset)
       offset += 1
 
       self.compress = (flags & FLAG_COMPRESSED) != 0
@@ -195,7 +197,7 @@ module SymmetricEncryption
 
     # Returns [String] this header as a string
     def to_s
-      flags = 0
+      flags  = 0
       flags |= FLAG_COMPRESSED if compressed?
       flags |= FLAG_IV if iv
       flags |= FLAG_KEY if key
@@ -256,9 +258,9 @@ module SymmetricEncryption
       #   Exception when
       #   - offset exceeds length of buffer
       #   byteslice truncates when too long, but returns nil when start is beyond end of buffer
-      len    = buffer.byteslice(offset, 2).unpack('v').first
+      len     = buffer.byteslice(offset, 2).unpack('v').first
       offset += 2
-      out    = buffer.byteslice(offset, len)
+      out     = buffer.byteslice(offset, len)
       [out, offset + len]
     end
   end

data/lib/symmetric_encryption/key.rb

@@ -3,68 +3,6 @@ module SymmetricEncryption
   class Key
     attr_reader :key, :iv, :cipher_name
 
-    # Returns [Key] from cipher data usually extracted from the configuration file.
-    #
-    # Supports N level deep key encrypting keys.
-    #
-    # Configuration keys:
-    # * key
-    # * encrypted_key
-    # * key_filename
-    def self.from_config(key: nil, key_filename: nil, encrypted_key: nil, key_env_var: nil,
-                         iv:, key_encrypting_key: nil, cipher_name: 'aes-256-cbc')
-
-      if key_encrypting_key.is_a?(Hash)
-        # Recurse up the chain returning the parent key_encrypting_key
-        key_encrypting_key = from_config(cipher_name: cipher_name, **key_encrypting_key)
-      end
-
-      key ||=
-        if encrypted_key
-          raise(ArgumentError, 'Missing mandatory :key_encrypting_key when config includes :encrypted_key') unless key_encrypting_key
-          Keystore::Memory.new(encrypted_key: encrypted_key, key_encrypting_key: key_encrypting_key).read
-        elsif key_filename
-          Keystore::File.new(file_name: key_filename, key_encrypting_key: key_encrypting_key).read
-        elsif key_env_var
-          raise(ArgumentError, 'Missing mandatory :key_encrypting_key when config includes :key_env_var') unless key_encrypting_key
-          Keystore::Environment.new(key_env_var: key_env_var, key_encrypting_key: key_encrypting_key).read
-        end
-
-      new(key: key, iv: iv, cipher_name: cipher_name)
-    end
-
-    # Migrate a prior config.
-    #
-    # Note:
-    # * The config cannot be saved back to the config file once
-    #   migrated, without generating new Key Encrypting Keys.
-    # * Only run this migration in the target environment so that the
-    #   current key encrypting files are present.
-    def self.migrate_config!(config)
-      # Backward compatibility - Deprecated
-      private_rsa_key = config.delete(:private_rsa_key)
-
-      # Migrate old encrypted_iv
-      if (encrypted_iv = config.delete(:encrypted_iv)) && private_rsa_key
-        encrypted_iv = RSAKey.new(private_rsa_key).decrypt(encrypted_iv)
-        config[:iv]  = ::Base64.decode64(encrypted_iv)
-      end
-
-      # Migrate old iv_filename
-      if (file_name = config.delete(:iv_filename)) && private_rsa_key
-        encrypted_iv = File.read(file_name)
-        config[:iv]  = RSAKey.new(private_rsa_key).decrypt(encrypted_iv)
-      end
-
-      # Backward compatibility - Deprecated
-      config[:key_encrypting_key] = RSAKey.new(private_rsa_key) if private_rsa_key
-
-      # Migrate old encrypted_key to new binary format
-      if (encrypted_key = config[:encrypted_key]) && private_rsa_key
-        config[:encrypted_key] = ::Base64.decode64(encrypted_key)
-      end
-    end
-
     def initialize(key: :random, iv: :random, cipher_name: 'aes-256-cbc')
       @key         = key == :random ? ::OpenSSL::Cipher.new(cipher_name).random_key : key
       @iv          = iv == :random ? ::OpenSSL::Cipher.new(cipher_name).random_iv : iv
@@ -73,6 +11,7 @@ module SymmetricEncryption
 
     def encrypt(string)
       return if string.nil?
+
       string = string.to_s
       return string if string.empty?
 
@@ -88,6 +27,7 @@ module SymmetricEncryption
 
     def decrypt(encrypted_string)
       return if encrypted_string.nil?
+
       encrypted_string = encrypted_string.to_s
       encrypted_string.force_encoding(SymmetricEncryption::BINARY_ENCODING)
       return encrypted_string if encrypted_string.empty?

data/lib/symmetric_encryption/keystore/aws.rb

@@ -0,0 +1,172 @@
+require 'base64'
+require 'aws-sdk-kms'
+module SymmetricEncryption
+  module Keystore
+    # Support AWS Key Management Service (KMS)
+    #
+    # Terms:
+    #   Aws
+    #     Amazon Web Services.
+    #
+    #   CMK
+    #     Customer Master Key.
+    #     Master key to encrypt and decrypt data, specifically the DEK in this case.
+    #     Stored in AWS, cannot be exported.
+    #
+    #   DEK
+    #     Data Encryption Key.
+    #     Key used to encrypt local data.
+    #     Encrypted with the CMK and stored locally.
+    #
+    #   KMS
+    #     Key Management Service.
+    #     For generating and storing the CMK.
+    #     Used to encrypt and decrypt the DEK.
+    #
+    # Recommended reading:
+    #
+    # Concepts:
+    #   https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html
+    #
+    # Overview:
+    #   https://docs.aws.amazon.com/kms/latest/developerguide/overview.html
+    #
+    # Process:
+    # 1. Create a customer master key (CMK) along with an alias for use by Symmetric Encryption.
+    #     - Note: CMK is region specific.
+    #     - Stored exclusively in AWS KMS, cannot be exported.
+    #
+    # 2. Generate and encrypt a data encryption key (DEK).
+    #     - CMK is used to encrypt the DEK.
+    #     - Encrypted DEK is stored locally.
+    #     - Encrypted DEK is region specific.
+    #       - DEK can be shared, but then must be re-encrypted in each region.
+    #     - Shared DEK across regions for database replication.
+    #     - List of regions to publish DEK to during generation / key-rotation.
+    #     - DEK must be encrypted with CMK in each region consecutively.
+    #
+    # Warning:
+    #   If access to the AWS KMS is ever lost, then it is not possible to decrypt any encrypted data.
+    #   Examples:
+    #     - Loss of access to AWS accounts.
+    #     - Loss of region(s) in which master keys are stored.
+    class Aws
+      attr_reader :region, :key_files, :master_key_alias
+
+      # Returns [Hash] a new keystore configuration after generating the data key.
+      #
+      # Increments the supplied version number by 1.
+      #
+      # Sample Hash layout returned:
+      # {
+      #   cipher_name: aes-256-cbc,
+      #   version:     8,
+      #   keystore:    :aws,
+      #   master_key_alias: 'alias/symmetric-encryption/application/production',
+      #   key_files:   [
+      #                  {region: blah1, file_name: "~/symmetric-encryption/application_production_blah1_v6.encrypted_key"},
+      #                  {region: blah2, file_name: "~/symmetric-encryption/application_production_blah2_v6.encrypted_key"},
+      #                ],
+      #   iv:          'T80pYzD0E6e/bJCdjZ6TiQ=='
+      # }
+      def self.generate_data_key(version: 0,
+                                 regions: Utils::Aws::AWS_US_REGIONS,
+                                 dek: nil,
+                                 cipher_name:,
+                                 app_name:,
+                                 environment:,
+                                 key_path:)
+
+        # TODO: Also support generating environment variables instead of files.
+
+        version >= 255 ? (version = 1) : (version += 1)
+        regions                   = Array(regions).dup
+
+        master_key_alias = master_key_alias(app_name, environment)
+
+        # File per region for holding the encrypted data key
+        key_files   = regions.collect do |region|
+          file_name = "#{app_name}_#{environment}_#{region}_v#{version}.encrypted_key"
+          {region: region, file_name: ::File.join(key_path, file_name)}
+        end
+
+        keystore = new(key_files: key_files, master_key_alias: master_key_alias)
+        unless dek
+          data_key = keystore.aws(regions.first).generate_data_key(cipher_name)
+          dek      = Key.new(key: data_key, cipher_name: cipher_name)
+        end
+        keystore.write(dek.key)
+
+        {
+          keystore:         :aws,
+          cipher_name:      dek.cipher_name,
+          version:          version,
+          master_key_alias: master_key_alias,
+          key_files:        key_files,
+          iv:               dek.iv
+        }
+      end
+
+      # Alias pointing to the active version of the master key for that region.
+      def self.master_key_alias(app_name, environment)
+        @master_key_alias ||= "alias/symmetric-encryption/#{app_name}/#{environment}"
+      end
+
+      # Stores the Encryption key in a file.
+      # Secures the Encryption key by encrypting it with a key encryption key.
+      def initialize(region: nil, key_files:, master_key_alias:, key_encrypting_key: nil)
+        @key_files        = key_files
+        @master_key_alias = master_key_alias
+        @region           = region || ENV['AWS_REGION'] || ENV['AWS_DEFAULT_REGION'] || ::Aws.config[:region]
+        if key_encrypting_key
+          raise(SymmetricEncryption::ConfigError, 'AWS KMS keystore encrypts the key itself, so does not support supplying a key_encrypting_key')
+        end
+      end
+
+      # Reads the data key environment variable, if present, otherwise a file.
+      # Decrypts the key using the master key for this region.
+      def read
+        key_file = key_files.find { |i| i[:region] == region }
+        raise(SymmetricEncryption::ConfigError, "region: #{region} not available in the supplied key_files") unless key_file
+
+        file_name = key_file[:file_name]
+        raise(SymmetricEncryption::ConfigError, 'file_name is mandatory for each key_file entry') unless file_name
+
+        raise(SymmetricEncryption::ConfigError, "File #{file_name} could not be found") unless ::File.exist?(file_name)
+
+        # TODO: Validate that file is not globally readable.
+        encoded_dek        = ::File.open(file_name, 'rb', &:read)
+        encrypted_data_key = Base64.strict_decode64(encoded_dek)
+        aws(region).decrypt(encrypted_data_key)
+      end
+
+      # Encrypt and write the data key to the file for each region.
+      def write(data_key)
+        key_files.each do |key_file|
+          region    = key_file[:region]
+          file_name = key_file[:file_name]
+
+          raise(ArgumentError, 'region and file_name are mandatory for each key_file entry') unless region && file_name
+
+          encrypted_data_key = aws(region).encrypt(data_key)
+          encoded_dek        = Base64.strict_encode64(encrypted_data_key)
+          write_to_file(file_name, encoded_dek)
+        end
+      end
+
+      def aws(region)
+        Utils::Aws.new(region: region, master_key_alias: master_key_alias)
+      end
+
+      private
+
+      # Write to the supplied file_name, backing up the existing file if present
+      def write_to_file(file_name, data)
+        path = ::File.dirname(file_name)
+        ::FileUtils.mkdir_p(path) unless ::File.directory?(path)
+        ::File.rename(file_name, "#{file_name}.#{Time.now.to_i}") if ::File.exist?(file_name)
+        ::File.open(file_name, 'wb') { |file| file.write(data) }
+      end
+    end
+  end
+end