kms_encrypted 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dcfe0e3ccdefdbde5b05b879a8f2badf3337fd0e
-  data.tar.gz: 8866251c5210f0c67845f99a221931db0a77446f
+  metadata.gz: 844c888ff1036e25341d665534193770b363f2d1
+  data.tar.gz: 042e30c929e4db3e7d7c18d692cc78ce220932c7
 SHA512:
-  metadata.gz: 664d6f021217bbd3e3740943bc91b60d1ad7af84c6f2081512f03956ba48488a98666a94417a61a1e68a15ccd36a8a4b31c541a6c40422a7cb8f21f079761d0f
-  data.tar.gz: dbd76c23ee501e1e7c8cb28d4cd1e45430e6ea3904ef4afa8053973b034f8637627c01646e9b5782079f24c151702aa2e3006940df99f572b73be9a8adad7a56
+  metadata.gz: 14e1be577cf7639c7f4eea48f1b03a56315adcd82d6efc4d38ecf6662793947202c4ded1f0d674eb860b60da4e8081a65515949a3810384c6c7b91d666d8bc9a
+  data.tar.gz: 359927d6b27361c62434e49be3b1a90d9498119d73a5f098f903eadbad4afef3a879bb61ee19d8f8d41753a91e11cbe461a4b79a307d6a4b06238a5908a9cbea

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.1.1
+
+- Added key rotation
+- Added support for multiple keys per record
+
 ## 0.1.0
 
 - First release

data/README.md

@@ -7,10 +7,18 @@ 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
 
-KMS addresses both of the issues and it’s easy to use them together.
+KMS addresses both issues and it’s easy to use them together.
 
 **Note:** This has not been battle-tested in a production environment, so use with caution
 
+## How It Works
+
+This approach uses KMS to manage encryption keys and attr_encrypted to do the encryption.
+
+To encrypt an attribute, we first generate a [data key](http://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) from our KMS master key. KMS sends both encrypted and unencrypted versions of the data key. 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.
+
 ## Getting Started
 
 Add this line to your application’s Gemfile:
@@ -49,6 +57,18 @@ For each encrypted attribute, use the `kms_key` method for its key.
 
 Add a `kms_encryption_context` method to your model.
 
+```ruby
+class User < ApplicationRecord
+  def kms_encryption_context
+    # some hash
+  end
+end
+```
+
+The context is used as part of the encryption and decryption process, so it must be a value that doesn’t change. Otherwise, you won’t be able to decrypt. Read more about [encryption context here](http://docs.aws.amazon.com/kms/latest/developerguide/encryption-context.html).
+
+The primary key is a good choice, but auto-generated ids aren’t available until a record is created, and we need to encrypt before this. One solution is to preload the primary key. Here’s what it looks like with Postgres:
+
 ```ruby
 class User < ApplicationRecord
   def kms_encryption_context
@@ -58,17 +78,130 @@ class User < ApplicationRecord
 end
 ```
 
-The context is used as part of the encryption and decryption process, so it must be a value that doesn’t change. Otherwise, you won’t be able to decrypt.
+We recommend [Amazon Athena](https://aws.amazon.com/athena/) for querying CloudTrail logs. Create a table (thanks to [this post](http://www.1strategy.com/blog/2017/07/25/auditing-aws-activity-with-cloudtrail-and-athena/) for the table structure) with:
+
+```sql
+CREATE EXTERNAL TABLE cloudtrail_logs (
+    eventversion STRING,
+    userIdentity STRUCT<
+        type:STRING,
+        principalid:STRING,
+        arn:STRING,
+        accountid:STRING,
+        invokedby:STRING,
+        accesskeyid:STRING,
+        userName:String,
+        sessioncontext:STRUCT<
+            attributes:STRUCT<
+                mfaauthenticated:STRING,
+                creationdate:STRING>,
+            sessionIssuer:STRUCT<
+                type:STRING,
+                principalId:STRING,
+                arn:STRING,
+                accountId:STRING,
+                userName:STRING>>>,
+    eventTime STRING,
+    eventSource STRING,
+    eventName STRING,
+    awsRegion STRING,
+    sourceIpAddress STRING,
+    userAgent STRING,
+    errorCode STRING,
+    errorMessage STRING,
+    requestId  STRING,
+    eventId  STRING,
+    resources ARRAY<STRUCT<
+        ARN:STRING,
+        accountId:STRING,
+        type:STRING>>,
+    eventType STRING,
+    apiVersion  STRING,
+    readOnly BOOLEAN,
+    recipientAccountId STRING,
+    sharedEventID STRING,
+    vpcEndpointId STRING,
+    requestParameters STRING,
+    responseElements STRING,
+    additionalEventData STRING,
+    serviceEventDetails STRING
+)
+ROW FORMAT SERDE 'com.amazon.emr.hive.serde.CloudTrailSerde'
+STORED  AS INPUTFORMAT 'com.amazon.emr.cloudtrail.CloudTrailInputFormat'
+OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat'
+LOCATION  's3://my-cloudtrail-logs/'
+```
 
-Read more about [encryption context here](http://docs.aws.amazon.com/kms/latest/developerguide/encryption-context.html).
+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'
+ORDER BY 1
+```
 
-## How It Works
+## 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.
+
+To manually rotate keys, replace the old KMS key id with the new key id in your model. Your app does not need the old key id to perform rotation (however, the key must still be enabled in your AWS account).
+
+```sh
+KMS_KEY_ID=arn:aws:kms:...
+```
+
+and run
+
+```sh
+User.find_each do |user|
+  user.rotate_kms_key!
+end
+```
+
+## Multiple Keys Per Record
+
+You may want to protect different columns with different data keys (or even master keys).
+
+To do this, add more columns
+
+```ruby
+add_column :users, :encrypted_kms_key_phone, :string
+```
+
+And update your model
+
+```ruby
+class User < ApplicationRecord
+  has_kms_key ENV["KMS_KEY_ID"]
+  has_kms_key ENV["KMS_KEY_ID"], name: :phone
 
-KMS allows you to generate data keys from your master key. Data keys are encrypted and stored with each record. Whenever you want to decrypt data, you need to first decrypt the data key with KMS. Once you have the decrypted key, you can then use it to decrypt the data with attr_encrypted.
+  attr_encrypted :email, key: :kms_key
+  attr_encrypted :phone, key: :kms_key_phone
+end
+```
 
-## TODO
+For context, use:
 
-- add support for multiple data keys per record
+```ruby
+class User < ApplicationRecord
+  def kms_encryption_context_phone
+    # some hash
+  end
+end
+```
+
+To rotate keys, use:
+
+```ruby
+user.rotate_kms_key_phone!
+```
 
 ## History
 

data/lib/kms_encrypted/version.rb

@@ -1,3 +1,3 @@
 module KmsEncrypted
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/kms_encrypted.rb

@@ -8,43 +8,63 @@ module KmsEncrypted
   end
 
   module Model
-    def has_kms_key(key_id)
+    def has_kms_key(key_id, name: nil)
       raise ArgumentError, "Missing key id" unless key_id
 
+      key_method = name ? "kms_key_#{name}" : "kms_key"
+
       class_eval do
-        class << self
-          attr_accessor :kms_key_id
-        end
-        self.kms_key_id = key_id
+        define_method(key_method) do
+          instance_var = "@#{key_method}"
 
-        def kms_key
-          unless @kms_key
-            key_id = self.class.kms_key_id
-            context = respond_to?(:kms_encryption_context) ? kms_encryption_context : {}
+          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"
 
-            unless encrypted_kms_key
+            unless send(key_column)
               resp = KmsEncrypted.kms.generate_data_key(
                 key_id: key_id,
                 encryption_context: context,
                 key_spec: "AES_256"
               )
-              @kms_key = resp.plaintext
               ciphertext = resp.ciphertext_blob
-              self.encrypted_kms_key = [resp.ciphertext_blob].pack(default_encoding)
+              instance_variable_set(instance_var, resp.plaintext)
+              self.send("#{key_column}=", [resp.ciphertext_blob].pack(default_encoding))
             end
 
-            unless @kms_key
-              ciphertext = encrypted_kms_key.unpack(default_encoding).first
+            unless instance_variable_get(instance_var)
+              ciphertext = send(key_column).unpack(default_encoding).first
               resp = KmsEncrypted.kms.decrypt(
                 ciphertext_blob: ciphertext,
                 encryption_context: context
               )
-              @kms_key = resp.plaintext
+              instance_variable_set(instance_var, resp.plaintext)
             end
           end
 
-          @kms_key
+          instance_variable_get(instance_var)
+        end
+
+        define_method("rotate_#{key_method}!") do
+          # decrypt
+          plaintext_attributes = {}
+          self.class.encrypted_attributes.select { |_, v| v[:key] == key_method.to_sym }.keys.each do |key|
+            plaintext_attributes[key] = send(key)
+          end
+
+          # reset key
+          instance_variable_set("@#{key_method}", nil)
+          send("encrypted_#{key_method}=", nil)
+
+          # encrypt again
+          plaintext_attributes.each do |attr, value|
+            send("#{attr}=", value)
+          end
+
+          # update atomically
+          save!
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kms_encrypted
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Andrew Kane