{"id":13879804,"url":"https://github.com/ankane/kms_encrypted","last_synced_at":"2025-11-17T14:11:18.861Z","repository":{"id":41165435,"uuid":"104607223","full_name":"ankane/kms_encrypted","owner":"ankane","description":"Simple, secure key management for Lockbox and attr_encrypted","archived":false,"fork":false,"pushed_at":"2025-10-22T05:16:34.000Z","size":251,"stargazers_count":259,"open_issues_count":1,"forks_count":25,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-11-04T22:14:58.684Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ankane.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-09-24T00:16:14.000Z","updated_at":"2025-11-04T09:50:52.000Z","dependencies_parsed_at":"2025-02-28T11:20:45.615Z","dependency_job_id":"eac6a361-7a5a-43a5-9886-cce5f2521b3b","html_url":"https://github.com/ankane/kms_encrypted","commit_stats":{"total_commits":273,"total_committers":8,"mean_commits":34.125,"dds":0.575091575091575,"last_synced_commit":"6e9c74a0e56d477173c4dd9e826deed4d759c356"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/ankane/kms_encrypted","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fkms_encrypted","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fkms_encrypted/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fkms_encrypted/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fkms_encrypted/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ankane","download_url":"https://codeload.github.com/ankane/kms_encrypted/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fkms_encrypted/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284894025,"owners_count":27080625,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-17T02:00:06.431Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T08:02:33.981Z","updated_at":"2025-11-17T14:11:18.856Z","avatar_url":"https://github.com/ankane.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# KMS Encrypted\n\nSimple, secure key management for [Lockbox](https://github.com/ankane/lockbox) and [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted)\n\nWith KMS Encrypted:\n\n- Master encryption keys are not on application servers\n- Encrypt and decrypt permissions can be granted separately\n- There’s an immutable audit log of all activity\n- Decryption can be disabled if an attack is detected\n- It’s easy to rotate keys\n\nSupports [AWS KMS](https://aws.amazon.com/kms/), [Google Cloud KMS](https://cloud.google.com/kms/), [Vault](https://developer.hashicorp.com/vault), and [OpenBao](https://openbao.org/)\n\nCheck out [this post](https://ankane.org/sensitive-data-rails) for more info on securing sensitive data with Rails\n\n[![Build Status](https://github.com/ankane/kms_encrypted/actions/workflows/build.yml/badge.svg)](https://github.com/ankane/kms_encrypted/actions)\n\n## How It Works\n\nThis approach uses a key management service (KMS) to manage encryption keys and Lockbox / attr_encrypted to do the encryption.\n\nTo encrypt an attribute, we first generate a data key and encrypt it with the KMS. This is known as [envelope encryption](https://cloud.google.com/kms/docs/envelope-encryption). We pass the unencrypted version to the encryption library and store the encrypted version in the `encrypted_kms_key` column. For each record, we generate a different data key.\n\nTo decrypt an attribute, we first decrypt the data key with the KMS. Once we have the decrypted key, we pass it to the encryption library to decrypt the data. We can easily track decryptions since we have a different data key for each record.\n\n## Installation\n\nAdd this line to your application’s Gemfile:\n\n```ruby\ngem \"kms_encrypted\"\n```\n\nAnd follow the instructions for your key management service:\n\n- [AWS KMS](#aws-kms)\n- [Google Cloud KMS](#google-cloud-kms)\n- [Vault and OpenBao](#vault-and-openbao)\n\n### AWS KMS\n\nAdd this line to your application’s Gemfile:\n\n```ruby\ngem \"aws-sdk-kms\"\n```\n\nCreate 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.\n\nCreate 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)\n\n```sh\nKMS_KEY_ID=arn:aws:kms:...\nAWS_ACCESS_KEY_ID=...\nAWS_SECRET_ACCESS_KEY=...\n```\n\nYou can also use the alias\n\n```sh\nKMS_KEY_ID=alias/my-alias\n```\n\n### Google Cloud KMS\n\nAdd this line to your application’s Gemfile:\n\n```ruby\ngem \"google-cloud-kms\"\n```\n\nCreate 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.\n\nCreate 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)\n\n```sh\nKMS_KEY_ID=projects/my-project/locations/global/keyRings/my-key-ring/cryptoKeys/my-key\n```\n\n### Vault and OpenBao\n\nAdd this line to your application’s Gemfile:\n\n```ruby\ngem \"vault\"\n```\n\nEnable the transit secrets engine for [Vault](https://developer.hashicorp.com/vault/docs/secrets/transit) or [OpenBao](https://openbao.org/docs/secrets/transit/)\n\n```sh\nvault secrets enable transit\n# or\nbao secrets enable transit\n```\n\nAnd create a key\n\n```sh\nvault write -f transit/keys/my-key derived=true\n# or\nbao write -f transit/keys/my-key derived=true\n```\n\nSet it in your environment along with your credentials ([dotenv](https://github.com/bkeepers/dotenv) is great for this)\n\n```sh\nKMS_KEY_ID=vault/my-key\nVAULT_ADDR=http://127.0.0.1:8200\nVAULT_TOKEN=secret\n```\n\n## Getting Started\n\nCreate a migration to add a column for the encrypted KMS data keys\n\n```ruby\nadd_column :users, :encrypted_kms_key, :text\n```\n\nAnd update your model\n\n```ruby\nclass User \u003c ApplicationRecord\n  has_kms_key\n\n  # Lockbox fields\n  has_encrypted :email, key: :kms_key\n\n  # Lockbox files\n  encrypts_attached :license, key: :kms_key\n\n  # attr_encrypted fields\n  attr_encrypted :email, key: :kms_key\nend\n```\n\nFor each encrypted attribute, use the `kms_key` method for its key.\n\n## Auditing \u0026 Alerting\n\n### Context\n\nEncryption context is used in auditing to identify the data being decrypted. This is the model name and id by default. You can customize this with:\n\n```ruby\nclass User \u003c ApplicationRecord\n  def kms_encryption_context\n    {\n      model_name: model_name.to_s,\n      model_id: id\n    }\n  end\nend\n```\n\nThe 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. You can [rotate the context](#switching-context) without downtime if needed.\n\n### Order of Events\n\nSince the default context includes the id, the data key cannot be encrypted until the record has an id. For new records, the default flow is:\n\n1. Start a database transaction\n2. Insert the record, getting back the id\n3. Call KMS to encrypt the data key, passing the id as part of the context\n4. Update the `encrypted_kms_key` column\n5. Commit the database transaction\n\nWith Postgres, you can avoid a network call inside a transaction with:\n\n```ruby\nclass User \u003c ApplicationRecord\n  has_kms_key eager_encrypt: :fetch_id\nend\n```\n\nThis changes the flow to:\n\n1. Prefetch the id with the Postgres `nextval` function\n2. Call KMS to encrypt the data key, passing the id as part of the context\n3. Insert the record with the id and encrypted data key\n\nIf you don’t need the id from the database for context, you can use:\n\n```ruby\nclass User \u003c ApplicationRecord\n  has_kms_key eager_encrypt: true\nend\n```\n\n### AWS KMS\n\n[AWS CloudTrail](https://aws.amazon.com/cloudtrail/) logs all decryption calls. You can view them in the [CloudTrail console](https://console.aws.amazon.com/cloudtrail/home#/events?EventName=Decrypt). Note that it can take 20 minutes for events to show up. You can also use the AWS CLI.\n\n```sh\naws cloudtrail lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=Decrypt\n```\n\nIf you haven’t already, enable CloudTrail storage to S3 to ensure events are accessible after 90 days. Later, you can use Amazon Athena and this [table structure](https://www.1strategy.com/blog/2017/07/25/auditing-aws-activity-with-cloudtrail-and-athena/) to query them.\n\nRead more about [encryption context here](https://docs.aws.amazon.com/kms/latest/developerguide/encryption-context.html).\n\n#### Alerting\n\nSet up alerts for suspicious behavior. To get near real-time alerts (20-30 second delay), use CloudWatch Events.\n\nFirst, create a new SNS topic with a name like \"decryptions\". We’ll use this shortly.\n\nNext, open [CloudWatch Events](https://console.aws.amazon.com/cloudwatch/home#rules:) and create a rule to match “Events by Service”. Choose “Key Management Service (KMS)” as the service name and “AWS API Call via CloudTrail” as the event type. For operations, select “Specific Operations” and enter “Decrypt”.\n\nSelect the SNS topic created earlier as the target and save the rule.\n\nTo set up an alarm, go to [this page](https://console.aws.amazon.com/cloudwatch/home?#metricsV2:graph=%7E();namespace=AWS/Events;dimensions=RuleName) in CloudWatch Metrics. Find the rule and check “Invocations”. On the “Graphed Metrics” tab, change the statistic to “Sum” and the period to “1 minute”. Finally, click the bell icon to create an alarm for high number of decryptions.\n\nWhile the alarm we created isn’t super sophisticated, this setup provides a great foundation for alerting as your organization grows.\n\nYou can use the SNS topic or another target to send events to a log provider or [SIEM](https://en.wikipedia.org/wiki/Security_information_and_event_management), where can you do more advanced anomaly detection.\n\nYou should also use other tools to detect breaches, like an [IDS](https://www.alienvault.com/blogs/security-essentials/open-source-intrusion-detection-tools-a-quick-overview). You can use [Amazon GuardDuty](https://aws.amazon.com/guardduty/) if you run infrastructure on AWS.\n\n### Google Cloud KMS\n\nFollow the [instructions here](https://cloud.google.com/kms/docs/logging) to set up data access logging. There is not currently a way to see what data is being decrypted, since the additional authenticated data is not logged. For this reason, we recommend another KMS provider.\n\n### Vault and OpenBao\n\nFollow the instructions for [Vault](https://developer.hashicorp.com/vault/docs/audit) or [OpenBao](https://openbao.org/docs/audit/) to set up data access logging.\n\n**Note:** Vault and OpenBao will only verify this value if `derived` was set to true when creating the key. If this is not done, the context cannot be trusted.\n\nContext will show up hashed in the audit logs. To get the hash for a record, use:\n\n```ruby\nKmsEncrypted.context_hash(record.kms_encryption_context, path: \"file\")\n```\n\nThe `path` option should point to your audit device. Common paths are `file`, `syslog`, and `socket`.\n\n## Separate Permissions\n\nA great feature of KMS is the ability to grant encryption and decryption permission separately.\n\nBe extremely selective of servers you allow to decrypt.\n\nFor servers that can only encrypt, clear out the existing data and data key before assigning new values (otherwise, you’ll get a decryption error).\n\n```ruby\n# Lockbox\nuser.email_ciphertext = nil\nuser.encrypted_kms_key = nil\n\n# attr_encrypted\nuser.encrypted_email = nil\nuser.encrypted_email_iv = nil\nuser.encrypted_kms_key = nil\n```\n\n### AWS KMS\n\nTo encrypt the data, use an IAM policy with:\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Sid\": \"EncryptData\",\n            \"Effect\": \"Allow\",\n            \"Action\": \"kms:Encrypt\",\n            \"Resource\": \"arn:aws:kms:...\"\n        }\n    ]\n}\n```\n\nTo decrypt the data, use an IAM policy with:\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Sid\": \"DecryptData\",\n            \"Effect\": \"Allow\",\n            \"Action\": \"kms:Decrypt\",\n            \"Resource\": \"arn:aws:kms:...\"\n        }\n    ]\n}\n```\n\n### Google Cloud KMS\n\ntodo: document\n\n### Vault and OpenBao\n\nTo encrypt the data, use a policy with:\n\n```hcl\npath \"transit/encrypt/my-key\"\n{\n  capabilities = [\"create\", \"update\"]\n}\n```\n\nTo decrypt the data, use a policy with:\n\n```hcl\npath \"transit/decrypt/my-key\"\n{\n  capabilities = [\"create\", \"update\"]\n}\n```\n\nApply a policy with:\n\n```sh\nvault policy write encrypt encrypt.hcl\n# or\nbao policy write encrypt encrypt.hcl\n```\n\nAnd create a token with specific policies with:\n\n```sh\nvault token create -policy=encrypt -policy=decrypt -no-default-policy\n# or\nbao token create -policy=encrypt -policy=decrypt -no-default-policy\n```\n\n## Testing\n\nFor testing, you can prevent network calls to KMS by setting:\n\n```sh\nKMS_KEY_ID=insecure-test-key\n```\n\nIn a Rails application, you can also create `config/initializers/kms_encrypted.rb` with:\n\n```ruby\nKmsEncrypted.key_id = Rails.env.test? ? \"insecure-test-key\" : ENV[\"KMS_KEY_ID\"]\n```\n\n## Key Rotation\n\nKey management services allow you to rotate the master key without any code changes.\n\n- For AWS KMS, you can use [automatic key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)\n- For Google Cloud, use the Google Cloud Console or API\n- For Vault, use `vault write -f transit/keys/my-key/rotate`\n- For OpenBao, use `bao write -f transit/keys/my-key/rotate`\n\nNew data will be encrypted with the new master key version. To encrypt existing data with new master key version, run:\n\n```ruby\nUser.find_each do |user|\n  user.rotate_kms_key!\nend\n```\n\n**Note:** This method does not rotate encrypted files, so avoid calling `rotate_kms_key!` on models with file uploads for now.\n\n### Switching Keys\n\nYou can change keys within your current KMS or move to a different KMS without downtime. Update your model:\n\n```ruby\nclass User \u003c ApplicationRecord\n  has_kms_key version: 2, key_id: ENV[\"KMS_KEY_ID_V2\"],\n    previous_versions: {\n      1 =\u003e {key_id: ENV[\"KMS_KEY_ID\"]}\n    }\nend\n```\n\nNew data will be encrypted with the new key. To update existing data, use:\n\n```ruby\nUser.where(\"encrypted_kms_key NOT LIKE 'v2:%'\").find_each do |user|\n  user.rotate_kms_key!\nend\n```\n\nOnce all data is updated, you can remove the `previous_versions` option.\n\n### Switching Context\n\nYou can change your encryption context without downtime. Update your model:\n\n```ruby\nclass User \u003c ApplicationRecord\n  has_kms_key version: 2,\n    previous_versions: {\n      1 =\u003e {key_id: ENV[\"KMS_KEY_ID\"]}\n    }\n\n  def kms_encryption_context(version:)\n    if version == 1\n      # previous context method\n    else\n      # new context method\n    end\n  end\nend\n```\n\nNew data will be encrypted with the new context. To update existing data, use:\n\n```ruby\nUser.where(\"encrypted_kms_key NOT LIKE 'v2:%'\").find_each do |user|\n  user.rotate_kms_key!\nend\n```\n\nOnce all data is updated, you can remove the `previous_versions` option.\n\n## Multiple Keys Per Record\n\nYou may want to protect different columns with different data keys (or even master keys).\n\nTo do this, add another column\n\n```ruby\nadd_column :users, :encrypted_kms_key_phone, :text\n```\n\nAnd update your model\n\n```ruby\nclass User \u003c ApplicationRecord\n  has_kms_key\n  has_kms_key name: :phone, key_id: \"...\"\n\n  # Lockbox\n  has_encrypted :email, key: :kms_key\n  has_encrypted :phone, key: :kms_key_phone\n\n  # attr_encrypted\n  attr_encrypted :email, key: :kms_key\n  attr_encrypted :phone, key: :kms_key_phone\nend\n```\n\nTo rotate keys, use:\n\n```ruby\nuser.rotate_kms_key_phone!\n```\n\nFor custom context, use:\n\n```ruby\nclass User \u003c ApplicationRecord\n  def kms_encryption_context_phone\n    # some hash\n  end\nend\n```\n\n## Outside Models\n\nTo encrypt and decrypt outside of models, create a box:\n\n```ruby\nkms = KmsEncrypted::Box.new\n```\n\nYou can pass `key_id`, `version`, and `previous_versions` if needed.\n\nEncrypt\n\n```ruby\nkms.encrypt(message, context: {model_name: \"User\", model_id: 123})\n```\n\nDecrypt\n\n```ruby\nkms.decrypt(ciphertext, context: {model_name: \"User\", model_id: 123})\n```\n\n## Related Projects\n\nTo securely search encrypted data, check out [Blind Index](https://github.com/ankane/blind_index).\n\n## History\n\nView the [changelog](CHANGELOG.md)\n\n## Contributing\n\nEveryone is encouraged to help improve this project. Here are a few ways you can help:\n\n- [Report bugs](https://github.com/ankane/kms_encrypted/issues)\n- Fix bugs and [submit pull requests](https://github.com/ankane/kms_encrypted/pulls)\n- Write, clarify, or fix documentation\n- Suggest or add new features\n\nTo get started with development and testing:\n\n```sh\ngit clone https://github.com/ankane/kms_encrypted.git\ncd kms_encrypted\nbundle install\nbundle exec rake test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankane%2Fkms_encrypted","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fankane%2Fkms_encrypted","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankane%2Fkms_encrypted/lists"}