Simple, secure key management for attr_encrypted
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
guides DRY readme [skip ci] Jan 21, 2019
lib Version bump to 1.0.1 [skip ci] Jan 21, 2019
test Allow for proc context outside models Jan 21, 2019
.gitignore
.travis.yml Fixed gemfiles Dec 17, 2018
CHANGELOG.md Version bump to 1.0.1 [skip ci] Jan 21, 2019
Gemfile First commit Sep 24, 2017
LICENSE.txt
README.md Version bump to 1.0.1 [skip ci] Jan 21, 2019
Rakefile First commit Sep 24, 2017
kms_encrypted.gemspec Added min version of Active Support Dec 17, 2018

README.md

KMS Encrypted

Simple, secure key management for attr_encrypted

With KMS Encrypted:

  • Master encryption keys are not on application servers
  • Encrypt and decrypt permissions can be granted separately
  • There’s an immutable audit log of all activity
  • Decryption can be disabled if an attack is detected
  • It’s easy to rotate keys

Supports AWS KMS, Google Cloud KMS, and Vault

Check out this post for more info on securing sensitive data with Rails

Build Status

How It Works

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 the KMS. This is known as 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 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:

Outside Models

To encrypt and decrypt outside of models, create a box:

kms = KmsEncrypted::Box.new

You can pass key_id, version, and previous_versions if needed.

Encrypt

kms.encrypt(message, context: {model_name: "User", model_id: 123})

Decrypt

kms.decrypt(ciphertext, context: {model_name: "User", model_id: 123})

Related Projects

To securely search encrypted data, check out 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:

class User < ApplicationRecord
  has_kms_key upgrade_context: true
end

Then run:

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

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help: