kms_encrypted 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bec6f5799315832f67c01e6ffe79b58a5c5019e3ca8efa5a2c0795149a2b727c
-  data.tar.gz: 8cbea27c197f2da4dbd1cad3bbee59c36c2404cd8eddb379c07be7ebbfc72a05
+  metadata.gz: 11c711222f049df42c663c9e68a2822fb7e318d3f3fc02f6346801c998ead328
+  data.tar.gz: 98200a87d8bf02a7398b075aaa6d79dff706a4d15d850584ebd952329980520b
 SHA512:
-  metadata.gz: ba30a61a50245321fcca825ce5d36a4f350edb26b832f033d029b6051578a1f6d3ac8efb81f01339762a1a6869f6e70ca4a4fc780d3341ea80b4d17ca57724e8
-  data.tar.gz: e511299714c5d035f000d7e85de6855be813fccc0a65fe7332a9418e0dc2733c6618ae42070f582877b48db98117aabc9b605ab1931537885180b20693fb7da0
+  metadata.gz: 7b3d37f2739f1a869a8a34c62e9300c3b54b0e8b87b98377883fa252d161aaafcb387044049bf0bfb070e86d481034bcf5c19b0e83d21a4668a513b02f3da151
+  data.tar.gz: b5596bc03466ac15b09d72cd1e00093eda05e2dcd3ca17607484ff678da808647bb7d364be27b5cfc912cdcccb991cbb55b18fd94206a4cb4510d17eaeb4c0da

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 1.0.0
+
+- Added versioning
+- Added `context_hash` method
+
+Breaking changes
+
+- There’s now a default encryption context with the model name and id
+- ActiveSupport notifications were changed from `generate_data_key` and `decrypt_data_key` to `encrypt` and `decrypt`
+- AWS KMS uses the `Encrypt` operation instead of `GenerateDataKey`
+
 ## 0.3.0
 
 - Added support for Vault

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2017 Andrew Kane
+Copyright (c) 2017-2018 Andrew Kane
 
 MIT License
 

data/README.md

@@ -2,39 +2,66 @@
 
 Simple, secure key management for [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted)
 
-The attr_encrypted gem is great for encryption, but:
+With KMS Encrypted:
 
-1. Leaves you to manage the security of your keys
-2. Doesn’t provide an easy way to rotate your keys
-3. Doesn’t have a great audit trail to see how data has been accessed
-4. Doesn’t let you grant encryption and decryption permission separately
+- Master encryption keys are not on application servers
+- There’s an immutable audit log of all activity
+- Decryption can be disabled if an attack is detected
+- Encrypt and decrypt permissions can be granted separately
+- It’s easy to rotate keys
 
-Key management services address all of these issues and it’s easy to use them together.
-
-Supports [Amazon KMS](https://aws.amazon.com/kms/), [Google KMS](https://cloud.google.com/kms/), and [Vault](https://www.vaultproject.io/)
+Supports [AWS KMS](https://aws.amazon.com/kms/), [Google Cloud KMS](https://cloud.google.com/kms/), and [Vault](https://www.vaultproject.io/)
 
 [![Build Status](https://travis-ci.org/ankane/kms_encrypted.svg?branch=master)](https://travis-ci.org/ankane/kms_encrypted)
 
 ## How It Works
 
-This approach uses KMS to manage encryption keys and attr_encrypted to do the encryption.
+This approach uses a key management service (KMS) to manage encryption keys and attr_encrypted to do the encryption.
 
-To encrypt an attribute, we first generate a data key and encrypt it with KMS. This is known as [envelope encryption](https://cloud.google.com/kms/docs/envelope-encryption). We pass the unencrypted version to attr_encrypted and store the encrypted version in the `encrypted_kms_key` column. For each record, we generate a different data key.
+To encrypt an attribute, we first generate a data key and encrypt it with the KMS. This is known as [envelope encryption](https://cloud.google.com/kms/docs/envelope-encryption). We pass the unencrypted version to attr_encrypted and store the encrypted version in the `encrypted_kms_key` column. For each record, we generate a different data key.
 
-To decrypt an attribute, we first decrypt the data key with KMS. Once we have the decrypted key, we pass it to attr_encrypted to decrypt the data. We can easily track decryptions since we have a different data key for each record.
+To decrypt an attribute, we first decrypt the data key with the KMS. Once we have the decrypted key, we pass it to attr_encrypted to decrypt the data. We can easily track decryptions since we have a different data key for each record.
 
 ## Getting Started
 
 Follow the instructions for your key management service:
 
-- [Amazon KMS](guides/Amazon.md)
-- [Google KMS](guides/Google.md)
+- [AWS KMS](guides/Amazon.md)
+- [Google Cloud KMS](guides/Google.md)
 - [Vault](guides/Vault.md)
 
 ## Related Projects
 
 To securely search encrypted data, check out [Blind Index](https://github.com/ankane/blind_index).
 
+## Upgrading
+
+### 1.0
+
+KMS Encrypted 1.0 brings a number of improvements. Here are a few breaking changes to be aware of:
+
+- There’s now a default encryption context with the model name and id
+- ActiveSupport notifications were changed from `generate_data_key` and `decrypt_data_key` to `encrypt` and `decrypt`
+- AWS KMS uses the `Encrypt` operation instead of `GenerateDataKey`
+
+If you didn’t previously use encryption context, add the `upgrade_context` option to your models:
+
+```ruby
+class User < ApplicationRecord
+  has_kms_key upgrade_context: true
+end
+```
+
+Then run:
+
+```ruby
+User.where("encrypted_kms_key NOT LIKE 'v1:%'").find_each do |user|
+  user.rotate_kms_key!
+end
+```
+
+And remove the `upgrade_context` option.
+
 ## History
 
 View the [changelog](CHANGELOG.md)

data/lib/kms_encrypted/client.rb

@@ -0,0 +1,69 @@
+module KmsEncrypted
+  class Client
+    delegate :encrypt, :decrypt, to: :client
+
+    attr_reader :key_id, :data_key
+
+    def initialize(key_id: nil, legacy_context: false, data_key: false)
+      @key_id = key_id || ENV["KMS_KEY_ID"]
+      @legacy_context = legacy_context
+      @data_key = data_key
+    end
+
+    def encrypt(plaintext, context: nil)
+      event = {
+        key_id: key_id,
+        context: context,
+        data_key: data_key
+      }
+
+      ActiveSupport::Notifications.instrument("encrypt.kms_encrypted", event) do
+        client.encrypt(plaintext, context: context)
+      end
+    end
+
+    def decrypt(ciphertext, context: nil)
+      event = {
+        key_id: key_id,
+        context: context,
+        data_key: data_key
+      }
+
+      ActiveSupport::Notifications.instrument("decrypt.kms_encrypted", event) do
+        client.decrypt(ciphertext, context: context)
+      end
+    end
+
+    private
+
+    def provider
+      if key_id == "insecure-test-key"
+        :test
+      elsif key_id.start_with?("vault/")
+        :vault
+      elsif key_id.start_with?("projects/")
+        :google
+      else
+        :aws
+      end
+    end
+
+    def client
+      @client ||= begin
+        klass =
+          case provider
+          when :test
+            KmsEncrypted::Clients::Test
+          when :vault
+            KmsEncrypted::Clients::Vault
+          when :google
+            KmsEncrypted::Clients::Google
+          else
+            KmsEncrypted::Clients::Aws
+          end
+
+        klass.new(key_id: key_id, legacy_context: @legacy_context)
+      end
+    end
+  end
+end

data/lib/kms_encrypted/clients/aws.rb

@@ -0,0 +1,36 @@
+module KmsEncrypted
+  module Clients
+    class Aws < Base
+      def encrypt(plaintext, context: nil)
+        options = {
+          key_id: key_id,
+          plaintext: plaintext
+        }
+        options[:encryption_context] = generate_context(context) if context
+
+        KmsEncrypted.aws_client.encrypt(options).ciphertext_blob
+      end
+
+      def decrypt(ciphertext, context: nil)
+        options = {
+          ciphertext_blob: ciphertext
+        }
+        options[:encryption_context] = generate_context(context) if context
+
+        begin
+          KmsEncrypted.aws_client.decrypt(options).plaintext
+        rescue ::Aws::KMS::Errors::InvalidCiphertextException
+          decryption_failed!
+        end
+      end
+
+      private
+
+      # make integers strings for convenience
+      def generate_context(context)
+        raise ArgumentError, "Context must be a hash" unless context.is_a?(Hash)
+        Hash[context.map { |k, v| [k, context_value(v)] }]
+      end
+    end
+  end
+end

data/lib/kms_encrypted/clients/base.rb

@@ -0,0 +1,45 @@
+module KmsEncrypted
+  module Clients
+    class Base
+      attr_reader :key_id
+
+      def initialize(key_id: nil, legacy_context: false)
+        @key_id = key_id
+        @legacy_context = legacy_context
+      end
+
+      protected
+
+      def decryption_failed!
+        raise DecryptionError, "Decryption failed"
+      end
+
+      # keys must be ordered consistently
+      # values are checked for validity
+      # then converted to strings
+      def generate_context(context)
+        if @legacy_context
+          context.to_json
+        elsif context.is_a?(Hash)
+          Hash[context.sort_by { |k| k.to_s }.map { |k, v| [context_key(k), context_value(v)] }].to_json
+        else
+          context
+        end
+      end
+
+      def context_key(k)
+        unless k.is_a?(String) || k.is_a?(Symbol)
+          raise ArgumentError, "Context keys must be a string or symbol"
+        end
+        k.to_s
+      end
+
+      def context_value(v)
+        unless v.is_a?(String) || v.is_a?(Integer)
+          raise ArgumentError, "Context values must be a string or integer"
+        end
+        v.to_s
+      end
+    end
+  end
+end

data/lib/kms_encrypted/clients/google.rb

@@ -0,0 +1,40 @@
+module KmsEncrypted
+  module Clients
+    class Google < Base
+      attr_reader :last_key_version
+
+      def encrypt(plaintext, context: nil)
+        options = {
+          plaintext: plaintext
+        }
+        options[:additional_authenticated_data] = generate_context(context) if context
+
+        # ensure namespace gets loaded
+        client = KmsEncrypted.google_client
+        request = ::Google::Apis::CloudkmsV1::EncryptRequest.new(options)
+        response = client.encrypt_crypto_key(key_id, request)
+
+        @last_key_version = response.name
+
+        response.ciphertext
+      end
+
+      def decrypt(ciphertext, context: nil)
+        options = {
+          ciphertext: ciphertext
+        }
+        options[:additional_authenticated_data] = generate_context(context) if context
+
+        # ensure namespace gets loaded
+        client = KmsEncrypted.google_client
+        request = ::Google::Apis::CloudkmsV1::DecryptRequest.new(options)
+        begin
+          client.decrypt_crypto_key(key_id, request).plaintext
+        rescue ::Google::Apis::ClientError => e
+          decryption_failed! if e.message.include?("Decryption failed")
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/kms_encrypted/clients/test.rb

@@ -0,0 +1,29 @@
+module KmsEncrypted
+  module Clients
+    class Test < Base
+      PREFIX = Base64.decode64("insecure+data+A")
+
+      def encrypt(plaintext, context: nil)
+        parts = [PREFIX, Base64.strict_encode64(plaintext)]
+        parts << generate_context(context) if context
+        parts.join(":")
+      end
+
+      def decrypt(ciphertext, context: nil)
+        prefix, plaintext, stored_context = ciphertext.split(":")
+
+        context = generate_context(context) if context
+        decryption_failed! if context != stored_context
+
+        Base64.decode64(plaintext)
+      end
+
+      private
+
+      # turn hash into json
+      def generate_context(context)
+        Base64.encode64(super)
+      end
+    end
+  end
+end

data/lib/kms_encrypted/clients/vault.rb

@@ -0,0 +1,48 @@
+module KmsEncrypted
+  module Clients
+    class Vault < Base
+      def encrypt(plaintext, context: nil)
+        options = {
+          plaintext: Base64.encode64(plaintext)
+        }
+        options[:context] = generate_context(context) if context
+
+        response = KmsEncrypted.vault_client.logical.write(
+          "transit/encrypt/#{key_id.sub("vault/", "")}",
+          options
+        )
+
+        response.data[:ciphertext]
+      end
+
+      def decrypt(ciphertext, context: nil)
+        options = {
+          ciphertext: ciphertext
+        }
+        options[:context] = generate_context(context) if context
+
+        response =
+          begin
+            KmsEncrypted.vault_client.logical.write(
+              "transit/decrypt/#{key_id.sub("vault/", "")}",
+              options
+            )
+          rescue ::Vault::HTTPClientError => e
+            decryption_failed! if e.message.include?("unable to decrypt")
+            raise e
+          rescue Encoding::UndefinedConversionError
+            decryption_failed!
+          end
+
+        Base64.decode64(response.data[:plaintext])
+      end
+
+      private
+
+      # turn hash into json
+      def generate_context(context)
+        Base64.encode64(super)
+      end
+    end
+  end
+end

data/lib/kms_encrypted/database.rb

@@ -0,0 +1,93 @@
+module KmsEncrypted
+  class Database
+    attr_reader :record, :key_method, :options
+
+    def initialize(record, key_method)
+      @record = record
+      @key_method = key_method
+      @options = record.class.kms_keys[key_method.to_sym]
+    end
+
+    def name
+      options[:name]
+    end
+
+    def current_version
+      @version ||= begin
+        version = options[:version]
+        version = record.instance_exec(&version) if version.respond_to?(:call)
+        version.to_i
+      end
+    end
+
+    def key_version(version)
+      versions = (options[:previous_versions] || {}).dup
+      versions[current_version] ||= options.slice(:key_id)
+
+      raise KmsEncrypted::Error, "Version not active: #{version}" unless versions[version]
+
+      key_id = versions[version][:key_id]
+
+      raise ArgumentError, "Missing key id" unless key_id
+
+      key_id
+    end
+
+    def context(version)
+      context_method = name ? "kms_encryption_context_#{name}" : "kms_encryption_context"
+      if record.method(context_method).arity == 0
+        record.send(context_method)
+      else
+        record.send(context_method, version: version)
+      end
+    end
+
+    def encrypt(plaintext)
+      key_id = key_version(current_version)
+      context = context(current_version)
+      ciphertext = KmsEncrypted::Client.new(key_id: key_id, data_key: true).encrypt(plaintext, context: context)
+      "v#{current_version}:#{encode64(ciphertext)}"
+    end
+
+    def decrypt(ciphertext)
+      m = /\Av(\d+):/.match(ciphertext)
+      if m
+        version = m[1].to_i
+        ciphertext = ciphertext.sub("v#{version}:", "")
+      else
+        version = 1
+        context = {} if options[:upgrade_context]
+        legacy_context = true
+
+        # legacy
+        if ciphertext.start_with?("$gc$")
+          _, _, short_key_id, ciphertext = ciphertext.split("$", 4)
+
+          # restore key, except for cryptoKeyVersion
+          stored_key_id = decode64(short_key_id).split("/")[0..3]
+          stored_key_id.insert(0, "projects")
+          stored_key_id.insert(2, "locations")
+          stored_key_id.insert(4, "keyRings")
+          stored_key_id.insert(6, "cryptoKeys")
+          key_id = stored_key_id.join("/")
+        elsif ciphertext.start_with?("vault:")
+          ciphertext = Base64.encode64(ciphertext)
+        end
+      end
+
+      key_id ||= key_version(version)
+      context ||= context(version)
+      ciphertext = decode64(ciphertext)
+
+      KmsEncrypted::Client.new(key_id: key_id, data_key: true, legacy_context: legacy_context).decrypt(ciphertext, context: context)
+    end
+
+    def encode64(bytes)
+      Base64.strict_encode64(bytes)
+    end
+
+    def decode64(bytes)
+      Base64.decode64(bytes)
+    end
+  end
+end

data/lib/kms_encrypted/log_subscriber.rb

@@ -1,17 +1,25 @@
 module KmsEncrypted
   class LogSubscriber < ActiveSupport::LogSubscriber
-    def decrypt_data_key(event)
+    def decrypt(event)
       return unless logger.debug?
 
-      name = "Decrypt Data Key (#{event.duration.round(1)}ms)"
-      debug "  #{color(name, YELLOW, true)}  Context: #{event.payload[:context].inspect}"
+      data_key = event.payload[:data_key]
+      name = data_key ? "Decrypt Data Key" : "Decrypt"
+      name += " (#{event.duration.round(1)}ms)"
+      context = event.payload[:context]
+      context = context.inspect if context.is_a?(Hash)
+      debug "  #{color(name, YELLOW, true)}  Context: #{context}"
     end
 
-    def generate_data_key(event)
+    def encrypt(event)
       return unless logger.debug?
 
-      name = "Generate Data Key (#{event.duration.round(1)}ms)"
-      debug "  #{color(name, YELLOW, true)}  Context: #{event.payload[:context].inspect}"
+      data_key = event.payload[:data_key]
+      name = data_key ? "Encrypt Data Key" : "Encrypt"
+      name += " (#{event.duration.round(1)}ms)"
+      context = event.payload[:context]
+      context = context.inspect if context.is_a?(Hash)
+      debug "  #{color(name, YELLOW, true)}  Context: #{context}"
     end
   end
 end