active_kms 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ef69ec3793d206e0f6dc11c39de7d61af017d4c743441c20592411fab4ed54c
+  data.tar.gz: 7ddc9779bf39ce4dbbcbb52bb4f58a33407916cb58865de66aa761b4dd0da12a
+SHA512:
+  metadata.gz: 8285f7d2a15d25507104264c66c29dfbc6fe745d0161a860d8cd9115f75b1748d574cdcf3e5a07557397f95fd51188bb7795eb2742c442cf37f6837502ef872e
+  data.tar.gz: 4240335bc026f1f36bdacdeb781b205cb4f809f81694bb83a3d69e10ee07e360ca50be999da68aa3236427b579f87c40998d7d8395d0d2438664fc15e300db1a

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0 (2021-12-14)
+
+- First release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Andrew Kane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,185 @@
+# Active KMS
+
+Simple, secure key management for [Active Record encryption](https://edgeguides.rubyonrails.org/active_record_encryption.html)
+
+**Note:** This project is experimental until Rails 7 is released. At the moment, encryption requires three encryption requests and one decryption request. See [this Rails issue](https://github.com/rails/rails/issues/42388) for more info. As a result, there’s no way to grant encryption and decryption permission separately.
+
+[![Build Status](https://github.com/ankane/active_kms/workflows/build/badge.svg?branch=master)](https://github.com/ankane/active_kms/actions)
+
+## Installation
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem "active_kms"
+```
+
+And follow the instructions for your key management service:
+
+- [AWS KMS](#aws-kms)
+- [Google Cloud KMS](#google-cloud-kms)
+- [Vault](#vault)
+
+### AWS KMS
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem "aws-sdk-kms"
+```
+
+Create an [Amazon Web Services](https://aws.amazon.com/) account if you don’t have one. KMS works great whether or not you run your infrastructure on AWS.
+
+Create a [KMS master key](https://console.aws.amazon.com/kms/home#/kms/keys) and set it in your environment along with your AWS credentials ([dotenv](https://github.com/bkeepers/dotenv) is great for this)
+
+```sh
+KMS_KEY_ID=alias/my-key
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+```
+
+And add to `config/application.rb`:
+
+```ruby
+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:
+
+```ruby
+gem "google-cloud-kms"
+```
+
+Create a [Google Cloud Platform](https://cloud.google.com/) 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](https://console.cloud.google.com/iam-admin/kms) and set it in your environment along with your GCP credentials ([dotenv](https://github.com/bkeepers/dotenv) is great for this)
+
+```sh
+KMS_KEY_ID=projects/my-project/locations/global/keyRings/my-key-ring/cryptoKeys/my-key
+```
+
+And add to `config/application.rb`:
+
+```ruby
+config.active_record.encryption.key_provider = ActiveKms::GoogleCloudKeyProvider.new(key_id: ENV["KMS_KEY_ID"])
+```
+
+### Vault
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem "vault"
+```
+
+Enable the [transit](https://www.vaultproject.io/docs/secrets/transit/index.html) secrets engine
+
+```sh
+vault secrets enable transit
+```
+
+And create a key
+
+```sh
+vault write -f transit/keys/my-key
+```
+
+Set it in your environment along with your Vault credentials ([dotenv](https://github.com/bkeepers/dotenv) is great for this)
+
+```sh
+KMS_KEY_ID=my-key
+VAULT_ADDR=http://127.0.0.1:8200
+VAULT_TOKEN=secret
+```
+
+And add to `config/application.rb`:
+
+```ruby
+config.active_record.encryption.key_provider = ActiveKms::VaultKeyProvider.new(key_id: ENV["KMS_KEY_ID"])
+```
+
+## Per-Attribute Keys
+
+Specify per-attribute keys
+
+```ruby
+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`:
+
+```ruby
+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](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)
+- For Google Cloud, use the Google Cloud Console or API
+- For Vault, use:
+
+```sh
+vault write -f transit/keys/my-key/rotate
+```
+
+New data will be encrypted with the new master key version.
+
+### Switching Keys
+
+You can change keys within your current KMS or move to a different KMS without downtime.
+
+Set globally in `config/application.rb`:
+
+```ruby
+config.active_record.encryption.previous = [{key_provider: ActiveKms::AwsKeyProvider.new(key_id: "...")}]
+```
+
+Or per-attribute:
+
+```ruby
+class User < ApplicationRecord
+  encrypts :email, previous: [{key_provider: ActiveKms::AwsKeyProvider.new(key_id: "...")}]
+end
+```
+
+## Reference
+
+Specify a client
+
+```ruby
+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](https://github.com/ankane/active_kms/blob/master/CHANGELOG.md)
+
+## Contributing
+
+Everyone is encouraged to help improve this project. Here are a few ways you can help:
+
+- [Report bugs](https://github.com/ankane/active_kms/issues)
+- Fix bugs and [submit pull requests](https://github.com/ankane/active_kms/pulls)
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+To get started with development:
+
+```sh
+git clone https://github.com/ankane/active_kms.git
+cd active_kms
+bundle install
+bundle exec rake test
+```

data/lib/active_kms/aws_key_provider.rb

@@ -0,0 +1,28 @@
+module ActiveKms
+  class AwsKeyProvider < BaseKeyProvider
+    private
+
+    def default_client
+      Aws::KMS::Client.new(
+        retry_limit: 1,
+        http_open_timeout: 2,
+        http_read_timeout: 2
+      )
+    end
+
+    def encrypt(key_id, data_key)
+      client.encrypt(key_id: key_id, plaintext: data_key).ciphertext_blob
+    end
+
+    def decrypt(_, encrypted_data_key)
+      client.decrypt(ciphertext_blob: encrypted_data_key).plaintext
+    end
+
+    # key is stored in ciphertext so don't need to store reference
+    # reference could be useful for multiple AWS clients
+    # so consider an option in the future
+    def key_id_header
+      "aws"
+    end
+  end
+end

data/lib/active_kms/base_key_provider.rb

@@ -0,0 +1,47 @@
+module ActiveKms
+  class BaseKeyProvider
+    attr_reader :key_id, :client
+
+    def initialize(key_id:, client: nil)
+      @key_id = key_id
+      @client = client || default_client
+    end
+
+    def encryption_key
+      data_key = ActiveRecord::Encryption.key_generator.generate_random_key
+      encrypted_data_key =
+        ActiveSupport::Notifications.instrument("encrypt.active_kms") do
+          encrypt(key_id, data_key)
+        end
+
+      key = ActiveRecord::Encryption::Key.new(data_key)
+      key.public_tags.encrypted_data_key = encrypted_data_key
+      key.public_tags.encrypted_data_key_id = key_id_header
+      key
+    end
+
+    def decryption_keys(encrypted_message)
+      return [] if encrypted_message.headers.encrypted_data_key_id != key_id_header
+
+      encrypted_data_key = encrypted_message.headers.encrypted_data_key
+      # rescue errors to try previous keys
+      # rescue outside Active Support notification for more intuitive output
+      begin
+        data_key =
+          ActiveSupport::Notifications.instrument("decrypt.active_kms") do
+            decrypt(key_id, encrypted_data_key)
+          end
+        [ActiveRecord::Encryption::Key.new(data_key)]
+      rescue => e
+        warn "[active_kms] #{e.class.name}: #{e.message}"
+        []
+      end
+    end
+
+    private
+
+    def key_id_header
+      @key_id_header ||= "#{prefix}/#{Digest::SHA1.hexdigest(key_id).first(4)}"
+    end
+  end
+end

data/lib/active_kms/google_cloud_key_provider.rb

@@ -0,0 +1,25 @@
+module ActiveKms
+  class GoogleCloudKeyProvider < BaseKeyProvider
+    private
+
+    def default_client
+      require "google/cloud/kms"
+
+      Google::Cloud::Kms.key_management_service do |config|
+        config.timeout = 2
+      end
+    end
+
+    def encrypt(key_id, data_key)
+      client.encrypt(name: key_id, plaintext: data_key).ciphertext
+    end
+
+    def decrypt(key_id, encrypted_data_key)
+      client.decrypt(name: key_id, ciphertext: encrypted_data_key).plaintext
+    end
+
+    def prefix
+      "gc"
+    end
+  end
+end

data/lib/active_kms/log_subscriber.rb

@@ -0,0 +1,17 @@
+module ActiveKms
+  class LogSubscriber < ActiveSupport::LogSubscriber
+    def decrypt(event)
+      return unless logger.debug?
+
+      name = "Decrypt Data Key (#{event.duration.round(1)}ms)"
+      debug "  #{color(name, YELLOW, true)}"
+    end
+
+    def encrypt(event)
+      return unless logger.debug?
+
+      name = "Encrypt Data Key (#{event.duration.round(1)}ms)"
+      debug "  #{color(name, YELLOW, true)}"
+    end
+  end
+end

data/lib/active_kms/test_key_provider.rb

@@ -0,0 +1,20 @@
+module ActiveKms
+  class TestKeyProvider < BaseKeyProvider
+    def initialize
+    end
+
+    private
+
+    def encrypt(_, data_key)
+      data_key
+    end
+
+    def decrypt(_, encrypted_data_key)
+      encrypted_data_key
+    end
+
+    def key_id_header
+      "test"
+    end
+  end
+end

data/lib/active_kms/vault_key_provider.rb

@@ -0,0 +1,22 @@
+module ActiveKms
+  class VaultKeyProvider < BaseKeyProvider
+    private
+
+    def default_client
+      Vault::Client.new
+    end
+
+    def encrypt(key_id, data_key)
+      client.logical.write("transit/encrypt/#{key_id}", plaintext: Base64.encode64(data_key)).data[:ciphertext]
+    end
+
+    def decrypt(key_id, encrypted_data_key)
+      Base64.decode64(client.logical.write("transit/decrypt/#{key_id}", ciphertext: encrypted_data_key).data[:plaintext])
+    end
+
+    # could store entire key_id in key_id_header but prefer reference
+    def prefix
+      "vt"
+    end
+  end
+end

data/lib/active_kms/version.rb

@@ -0,0 +1,3 @@
+module ActiveKms
+  VERSION = "0.1.0"
+end

data/lib/active_kms.rb

@@ -0,0 +1,19 @@
+# dependencies
+require "active_support"
+
+# modules
+require "active_kms/base_key_provider"
+require "active_kms/log_subscriber"
+require "active_kms/version"
+
+# providers
+require "active_kms/aws_key_provider"
+require "active_kms/google_cloud_key_provider"
+require "active_kms/test_key_provider"
+require "active_kms/vault_key_provider"
+
+module ActiveKms
+  class Error < StandardError; end
+end
+
+ActiveKms::LogSubscriber.attach_to :active_kms

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: active_kms
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrew Kane
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-12-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0.rc3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0.rc3
+description:
+email: andrew@ankane.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/active_kms.rb
+- lib/active_kms/aws_key_provider.rb
+- lib/active_kms/base_key_provider.rb
+- lib/active_kms/google_cloud_key_provider.rb
+- lib/active_kms/log_subscriber.rb
+- lib/active_kms/test_key_provider.rb
+- lib/active_kms/vault_key_provider.rb
+- lib/active_kms/version.rb
+homepage: https://github.com/ankane/active_kms
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.32
+signing_key:
+specification_version: 4
+summary: Simple, secure key management for Active Record encryption
+test_files: []