kms_encrypted 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4319f0f40f5294c89119d36ebaba64696eb9abeb
-  data.tar.gz: 46933afe998badcf3b95814e0d9c1144f432d822
+  metadata.gz: 48601fd1b07d25fafe4a14a508511bd3237ef486
+  data.tar.gz: 74add3ece85f95c4e1a2b5483b772c2075def8c4
 SHA512:
-  metadata.gz: 2ca6b3da8040d329ee3a4bac21e0a06e82c9c423fed259e62508dd92332196eac46034d3803760baffc3c312a7618594fd1c0caefe7b25ebc8b57305e176501d
-  data.tar.gz: 56520a00ea21504b321e6e93f8f43283cd37a1b75d84661cb4e2a85d2ead8dda11062eb307bb8b4258c26ebdc3b0fcad017d335e9e9471314e0f393e69632f50
+  metadata.gz: 1461f4cbdd77bb98eba915832ee402d1467f8ed5b3578295010ece703864da16418cc7925f78fc64ffc6ed1176e34c07cc5912556fea8b2f6726b872b669e56b
+  data.tar.gz: 6268c77a1f065ce79ebf1a2cf954a7d36265d96135b54be8aeabec96d5b72828b8929f69dcc2778bbee3eda8247f1735747af22ed6a814fdf2428fa5d5510673

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+rvm: 2.4.2
+gemfile:
+  - Gemfile
+sudo: false
+before_install: gem install bundler
+script: bundle exec rake test
+env:
+  - KMS_KEY_ID=insecure-test-key
+notifications:
+  email:
+    on_success: never
+    on_failure: change

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.1.3
+
+- Added test key
+- Added `client_options`
+- Allow private or protected `kms_encryption_context` method
+
 ## 0.1.2
 
 - Use `KMS_KEY_ID` env variable by default

data/README.md

@@ -1,15 +1,17 @@
 # KMS Encrypted
 
-[KMS](https://aws.amazon.com/kms/) + [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted)
+Simple, secure key management for [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted)
 
 The attr_encrypted gem is great for encryption, but:
 
 1. Leaves you to manage the security of your keys
-2. Doesn’t provide a great audit trail to see how data has been accessed
+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
 
-KMS addresses both issues and it’s easy to use them together.
+[KMS](https://aws.amazon.com/kms/) addresses all of these issues and it’s easy to use them together.
 
-**Note:** This has not been battle-tested in a production environment, so use with caution
+[![Build Status](https://travis-ci.org/ankane/kms_encrypted.svg?branch=master)](https://travis-ci.org/ankane/kms_encrypted)
 
 ## How It Works
 
@@ -27,18 +29,28 @@ Add this line to your application’s Gemfile:
 gem 'kms_encrypted'
 ```
 
-Add a column to store encrypted KMS data keys
+Add columns for the encrypted data and the encrypted KMS data keys
 
 ```ruby
-add_column :users, :encrypted_kms_key, :string
+add_column :users, :encrypted_email, :text
+add_column :users, :encrypted_email_iv, :text
+add_column :users, :encrypted_kms_key, :text
 ```
 
+Create an [Amazon Web Services](https://aws.amazon.com/) account if you don’t have one. KMS works great whether or not you use other AWS services.
+
 Create a [KMS master key](https://console.aws.amazon.com/iam/home#/encryptionKeys) and set it in your environment ([dotenv](https://github.com/bkeepers/dotenv) is great for this)
 
 ```sh
 KMS_KEY_ID=arn:aws:kms:...
 ```
 
+You can also use the alias
+
+```sh
+KMS_KEY_ID=alias/my-alias
+```
+
 And update your model
 
 ```ruby
@@ -137,16 +149,22 @@ Change the last line to point to your CloudTrail log bucket and query away
 ```sql
 SELECT
     eventTime,
-    eventName,
     userIdentity.userName,
     requestParameters
 FROM
     cloudtrail_logs
 WHERE
     eventName = 'Decrypt'
+    AND resources[1].arn = 'arn:aws:kms:...'
 ORDER BY 1
 ```
 
+There will also be `GenerateDataKey` events.
+
+## Alerting
+
+We recommend setting up alerts on suspicious behavior.
+
 ## Key Rotation
 
 KMS supports [automatic key rotation](http://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html). No action is required in this case.
@@ -165,6 +183,58 @@ User.find_each do |user|
 end
 ```
 
+## IAM Permissions
+
+A great feature of KMS is the ability to grant encryption and decryption permission separately.
+
+To encrypt the data, use a policy with:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "EncryptData",
+            "Effect": "Allow",
+            "Action": "kms:GenerateDataKey",
+            "Resource": "arn:aws:kms:..."
+        }
+    ]
+}
+```
+
+If a system can only encrypt, you must clear out existing data keys before updates.
+
+```ruby
+user.encrypted_kms_key = nil # before user.save
+```
+
+To decrypt the data, use a policy with:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "DecryptData",
+            "Effect": "Allow",
+            "Action": "kms:Decrypt",
+            "Resource": "arn:aws:kms:..."
+        }
+    ]
+}
+```
+
+Be extremely selective of systems you allow to decrypt.
+
+## Testing
+
+For testing, you can prevent network calls to KMS by setting:
+
+```sh
+KMS_KEY_ID=insecure-test-key
+```
+
 ## Multiple Keys Per Record
 
 You may want to protect different columns with different data keys (or even master keys).
@@ -172,7 +242,9 @@ You may want to protect different columns with different data keys (or even mast
 To do this, add more columns
 
 ```ruby
-add_column :users, :encrypted_kms_key_phone, :string
+add_column :users, :encrypted_phone, :text
+add_column :users, :encrypted_phone_iv, :text
+add_column :users, :encrypted_kms_key_phone, :text
 ```
 
 And update your model

data/kms_encrypted.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Andrew Kane"]
   spec.email         = ["andrew@chartkick.com"]
 
-  spec.summary       = "KMS + attr_encrypted"
+  spec.summary       = "Simple, secure key management for attr_encrypted"
   spec.homepage      = "https://github.com/ankane/kms_encrypted"
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|

data/lib/kms_encrypted.rb

@@ -3,45 +3,59 @@ require "active_support"
 require "aws-sdk-kms"
 
 module KmsEncrypted
+  class << self
+    attr_accessor :client_options
+  end
+  self.client_options = {
+    retry_limit: 2,
+    http_open_timeout: 2,
+    http_read_timeout: 2
+  }
+
   def self.kms
-    @kms ||= Aws::KMS::Client.new
+    @kms ||= Aws::KMS::Client.new(client_options)
   end
 
   module Model
     def has_kms_key(legacy_key_id = nil, name: nil, key_id: nil)
       key_id ||= legacy_key_id || ENV["KMS_KEY_ID"]
-      raise ArgumentError, "Missing key id" unless key_id
 
       key_method = name ? "kms_key_#{name}" : "kms_key"
 
       class_eval do
         define_method(key_method) do
+          raise ArgumentError, "Missing key id" unless key_id
+
           instance_var = "@#{key_method}"
 
           unless instance_variable_get(instance_var)
-            key_column = "encrypted_#{key_method}"
-            context_method = name ? "kms_encryption_context_#{name}" : "kms_encryption_context"
-            context = respond_to?(context_method) ? send(context_method) : {}
-            default_encoding = "m"
+            if key_id == "insecure-test-key"
+              instance_variable_set(instance_var, "00000000000000000000000000000000")
+            else
+              key_column = "encrypted_#{key_method}"
+              context_method = name ? "kms_encryption_context_#{name}" : "kms_encryption_context"
+              context = respond_to?(context_method, true) ? send(context_method) : {}
+              default_encoding = "m"
 
-            unless send(key_column)
-              resp = KmsEncrypted.kms.generate_data_key(
-                key_id: key_id,
-                encryption_context: context,
-                key_spec: "AES_256"
-              )
-              ciphertext = resp.ciphertext_blob
-              instance_variable_set(instance_var, resp.plaintext)
-              self.send("#{key_column}=", [resp.ciphertext_blob].pack(default_encoding))
-            end
+              unless send(key_column)
+                resp = KmsEncrypted.kms.generate_data_key(
+                  key_id: key_id,
+                  encryption_context: context,
+                  key_spec: "AES_256"
+                )
+                ciphertext = resp.ciphertext_blob
+                instance_variable_set(instance_var, resp.plaintext)
+                self.send("#{key_column}=", [resp.ciphertext_blob].pack(default_encoding))
+              end
 
-            unless instance_variable_get(instance_var)
-              ciphertext = send(key_column).unpack(default_encoding).first
-              resp = KmsEncrypted.kms.decrypt(
-                ciphertext_blob: ciphertext,
-                encryption_context: context
-              )
-              instance_variable_set(instance_var, resp.plaintext)
+              unless instance_variable_get(instance_var)
+                ciphertext = send(key_column).unpack(default_encoding).first
+                resp = KmsEncrypted.kms.decrypt(
+                  ciphertext_blob: ciphertext,
+                  encryption_context: context
+                )
+                instance_variable_set(instance_var, resp.plaintext)
+              end
             end
           end
 

data/lib/kms_encrypted/version.rb

@@ -1,3 +1,3 @@
 module KmsEncrypted
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kms_encrypted
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Andrew Kane
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-09-26 00:00:00.000000000 Z
+date: 2017-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-kms
@@ -130,6 +130,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
 - CHANGELOG.md
 - Gemfile
 - README.md
@@ -159,5 +160,5 @@ rubyforge_project:
 rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
-summary: KMS + attr_encrypted
+summary: Simple, secure key management for attr_encrypted
 test_files: []