ankane / active_kms

Simple, secure key management for Active Record encryption

Active KMS

Simple, secure key management for Active Record encryption

Note: At the moment, encryption requires three encryption requests and one decryption request. See this Rails issue for more info. As a result, there’s no way to grant encryption and decryption permission separately.

For Lockbox and attr_encrypted, check out KMS Encrypted

Installation

Add this line to your application’s Gemfile:

gem "active_kms"

And follow the instructions for your key management service:

• AWS KMS
• Google Cloud KMS
• Vault

AWS KMS

Add this line to your application’s Gemfile:

gem "aws-sdk-kms"

Create an Amazon Web Services account if you don’t have one. KMS works great whether or not you run your infrastructure on AWS.

Create a KMS master key and set it in your environment along with your AWS credentials (dotenv is great for this)

KMS_KEY_ID=alias/my-key
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

And add to config/application.rb:

config.active_record.encryption.key_provider = ActiveKms::AwsKeyProvider.new(key_id: ENV["KMS_KEY_ID"])

Google Cloud KMS

Add this line to your application’s Gemfile:

gem "google-cloud-kms"

Create a Google Cloud Platform account if you don’t have one. KMS works great whether or not you run your infrastructure on GCP.

Create a KMS key ring and key and set it in your environment along with your GCP credentials (dotenv is great for this)

KMS_KEY_ID=projects/my-project/locations/global/keyRings/my-key-ring/cryptoKeys/my-key

And add to config/application.rb:

config.active_record.encryption.key_provider = ActiveKms::GoogleCloudKeyProvider.new(key_id: ENV["KMS_KEY_ID"])

Vault

Add this line to your application’s Gemfile:

gem "vault"

Enable the transit secrets engine

vault secrets enable transit

And create a key

vault write -f transit/keys/my-key

Set it in your environment along with your Vault credentials (dotenv is great for this)

KMS_KEY_ID=my-key
VAULT_ADDR=http://127.0.0.1:8200
VAULT_TOKEN=secret

And add to config/application.rb:

config.active_record.encryption.key_provider = ActiveKms::VaultKeyProvider.new(key_id: ENV["KMS_KEY_ID"])

Per-Attribute Keys

Specify per-attribute keys

class User < ApplicationRecord
  encrypts :email, key_provider: ActiveKms::AwsKeyProvider.new(key_id: "...")
end

Testing

For testing, you can prevent network calls to KMS by adding to config/environments/test.rb:

config.active_record.encryption.key_provider = ActiveKms::TestKeyProvider.new

Key Rotation

Key management services allow you to rotate the master key without any code changes.

• For AWS KMS, you can use automatic key rotation
• For Google Cloud, use the Google Cloud Console or API
• For Vault, use:

vault write -f transit/keys/my-key/rotate

New data will be encrypted with the new master key version. To encrypt existing data with new master key version, run:

User.find_each do |user|
  user.encrypt
end

Switching Keys

You can change keys within your current KMS or move to a different KMS without downtime.

Set globally in config/application.rb:

config.active_record.encryption.previous = [{key_provider: ActiveKms::AwsKeyProvider.new(key_id: "...")}]

Or per-attribute:

class User < ApplicationRecord
  encrypts :email, previous: [{key_provider: ActiveKms::AwsKeyProvider.new(key_id: "...")}]
end

Reference

Specify a client

ActiveKms::AwsKeyProvider.new(client: Aws::KMS::Client.new, ...)
# or
ActiveKms::GoogleCloudKeyProvider.new(client: Google::Cloud::Kms.key_management_service, ...)
# or
ActiveKms::VaultKeyProvider.new(client: Vault::Client.new, ...)

History

View the changelog

Contributing

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

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

To get started with development:

git clone https://github.com/ankane/active_kms.git
cd active_kms
bundle install
bundle exec rake test

active_kms's Issues

key_derivation_salt is not configured.

Im trying to use this gem to encrypt data. Ive put into my application.rb the following line:
config.active_record.encryption.key_provider = ActiveKms::AwsKeyProvider.new(key_id: Figaro.env.KMS_KEY_ID)

But when I try saving my model I get the following error

/home/.rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/activerecord-7.0.2.4/lib/active_record/encryption/scheme.rb:85:in `validate_credential': 
key_derivation_salt is not configured. Please configure it via credential active_record_encryption.key_derivation_salt or by setting config.active_record.encryption.key_derivation_salt (ActiveRecord::Encryption::Errors::Configuration)

Previously I had this in my application.rb fiole

config.active_record.encryption.primary_key = Rails.application.credentials[:active_record_encryption][:primary_key]
config.active_record.encryption.deterministic_key = Rails.application.credentials[:active_record_encryption][:deterministic_key]
config.active_record.encryption.key_derivation_salt = Rails.application.credentials[:active_record_encryption][:key_derivation_salt]

but I removed it as I assumed I wouldnt need it if the activerecord encryption uses the KMS key. Is there something Im missing? Do i still need the default configuration?

Cut a new release for Rails 7.1?

Hello!

Currently it appears that the old log styling syntax is resulting in a noisy deprecation warning about using a boolean vs. bold: true for bolding a log line. The code has already been fixed as of c2d825c, it's just not released yet.

active_kms/lib/active_kms/log_subscriber.rb

Line 7 in 4f55451

debug " #{color(name, YELLOW, bold: true)}"

Could you cut a release with the change? Without it a frequent KMS-calling suite has a lot of this:

Bolding log text with a positional boolean is deprecated and will be removed 
in Rails 7.2. Use an option hash instead (eg. `color("my text", :red, bold: true)`).