📦 Modern encryption for Ruby and Rails
- Works with database fields, files, and strings
- Maximizes compatibility with existing code and libraries
- Makes migrating existing data and key rotation easy
- Has zero dependencies and many integrations
Learn the principles behind it, how to secure emails with Devise, and how to secure sensitive data in Rails.
Add this line to your application’s Gemfile:
gem "lockbox"
Generate a key
Lockbox.generate_key
Store the key with your other secrets. This is typically Rails credentials or an environment variable (dotenv is great for this). Be sure to use different keys in development and production.
Set the following environment variable with your key (you can use this one in development)
LOCKBOX_MASTER_KEY=0000000000000000000000000000000000000000000000000000000000000000
or add it to your credentials for each environment (rails credentials:edit --environment <env>
)
lockbox:
master_key: "0000000000000000000000000000000000000000000000000000000000000000"
or create config/initializers/lockbox.rb
with something like
Lockbox.master_key = Rails.application.credentials.lockbox[:master_key]
Then follow the instructions below for the data you want to encrypt.
Create a migration with:
class AddEmailCiphertextToUsers < ActiveRecord::Migration[8.0]
def change
add_column :users, :email_ciphertext, :text
end
end
Add to your model:
class User < ApplicationRecord
has_encrypted :email
end
You can use email
just like any other attribute.
User.create!(email: "hi@example.org")
If you need to query encrypted fields, check out Blind Index.
You can specify multiple fields in single line.
class User < ApplicationRecord
has_encrypted :email, :phone, :city
end
Fields are strings by default. Specify the type of a field with:
class User < ApplicationRecord
has_encrypted :birthday, type: :date
has_encrypted :signed_at, type: :datetime
has_encrypted :opens_at, type: :time
has_encrypted :active, type: :boolean
has_encrypted :salary, type: :integer
has_encrypted :latitude, type: :float
has_encrypted :longitude, type: :decimal
has_encrypted :video, type: :binary
has_encrypted :properties, type: :json
has_encrypted :settings, type: :hash
has_encrypted :messages, type: :array
has_encrypted :ip, type: :inet
end
Note: Use a text
column for the ciphertext in migrations, regardless of the type
Lockbox automatically works with serialized fields for maximum compatibility with existing code and libraries.
class User < ApplicationRecord
serialize :properties, JSON
store :settings, accessors: [:color, :homepage]
attribute :configuration, CustomType.new
has_encrypted :properties, :settings, :configuration
end
For Active Record Store, encrypt the column rather than individual accessors.
For StoreModel, use:
class User < ApplicationRecord
has_encrypted :configuration, type: Configuration.to_type
after_initialize do
self.configuration ||= {}
end
end
Validations work as expected with the exception of uniqueness. Uniqueness validations require a blind index.
You can use encrypted attributes in fixtures with:
test_user:
email_ciphertext: <%= User.generate_email_ciphertext("secret").inspect %>
Be sure to include the inspect
at the end or it won’t be encoded properly in YAML.
Lockbox makes it easy to encrypt an existing column without downtime.
Add a new column for the ciphertext, then add to your model:
class User < ApplicationRecord
has_encrypted :email, migrating: true
end
Backfill the data in the Rails console:
Lockbox.migrate(User)
Then update the model to the desired state:
class User < ApplicationRecord
has_encrypted :email
# remove this line after dropping email column
self.ignored_columns += ["email"]
end
Finally, drop the unencrypted column.
If adding blind indexes, mark them as migrating
during this process as well.
class User < ApplicationRecord
blind_index :email, migrating: true
end
If tracking changes to model attributes, be sure to remove or redact encrypted attributes.
PaperTrail
class User < ApplicationRecord
# for an encrypted history (still tracks ciphertext changes)
has_paper_trail skip: [:email]
# for no history (add blind indexes as well)
has_paper_trail skip: [:email, :email_ciphertext]
end
Audited
class User < ApplicationRecord
# for an encrypted history (still tracks ciphertext changes)
audited except: [:email]
# for no history (add blind indexes as well)
audited except: [:email, :email_ciphertext]
end
To decrypt data outside the model, use:
User.decrypt_email_ciphertext(user.email_ciphertext)
Note: Action Text uses direct uploads for files, which cannot be encrypted with application-level encryption like Lockbox. This only encrypts the database field.
Create a migration with:
class AddBodyCiphertextToRichTexts < ActiveRecord::Migration[8.0]
def change
add_column :action_text_rich_texts, :body_ciphertext, :text
end
end
Create config/initializers/lockbox.rb
with:
Lockbox.encrypts_action_text_body(migrating: true)
Migrate existing data:
Lockbox.migrate(ActionText::RichText)
Update the initializer:
Lockbox.encrypts_action_text_body
And drop the unencrypted column.
You can pass any Lockbox options to the encrypts_action_text_body
method.
Add to your model:
class User
field :email_ciphertext, type: String
has_encrypted :email
end
You can use email
just like any other attribute.
User.create!(email: "hi@example.org")
If you need to query encrypted fields, check out Blind Index.
You can migrate existing data similarly to Active Record.
Add to your model:
class User < ApplicationRecord
has_one_attached :license
encrypts_attached :license
end
Works with multiple attachments as well.
class User < ApplicationRecord
has_many_attached :documents
encrypts_attached :documents
end
There are a few limitations to be aware of:
- Variants and previews aren’t supported when encrypted
- Metadata like image width and height aren’t extracted when encrypted
- Direct uploads can’t be encrypted with application-level encryption like Lockbox, but can use server-side encryption
To serve encrypted files, use a controller action.
def license
user = User.find(params[:id])
send_data user.license.download, type: user.license.content_type
end
Use filename
to specify a filename or disposition: "inline"
to show inline.
Lockbox makes it easy to encrypt existing files without downtime.
Add to your model:
class User < ApplicationRecord
encrypts_attached :license, migrating: true
end
Migrate existing files:
Lockbox.migrate(User)
Then update the model to the desired state:
class User < ApplicationRecord
encrypts_attached :license
end
Add to your uploader:
class LicenseUploader < CarrierWave::Uploader::Base
encrypt
end
Encryption is applied to all versions after processing.
You can mount the uploader as normal. With Active Record, this involves creating a migration:
class AddLicenseToUsers < ActiveRecord::Migration[8.0]
def change
add_column :users, :license, :string
end
end
And updating the model:
class User < ApplicationRecord
mount_uploader :license, LicenseUploader
end
To serve encrypted files, use a controller action.
def license
user = User.find(params[:id])
send_data user.license.read, type: user.license.content_type
end
Use filename
to specify a filename or disposition: "inline"
to show inline.
Encrypt existing files without downtime. Create a new encrypted uploader:
class LicenseV2Uploader < CarrierWave::Uploader::Base
encrypt key: Lockbox.attribute_key(table: "users", attribute: "license")
end
Add a new column for the uploader, then add to your model:
class User < ApplicationRecord
mount_uploader :license_v2, LicenseV2Uploader
before_save :migrate_license, if: :license_changed?
def migrate_license
self.license_v2 = license
end
end
Migrate existing files:
User.find_each do |user|
if user.license? && !user.license_v2?
user.migrate_license
user.save!
end
end
Then update the model to the desired state:
class User < ApplicationRecord
mount_uploader :license, LicenseV2Uploader, mount_on: :license_v2
end
Finally, delete the unencrypted files and drop the column for the original uploader. You can also remove the key
option from the uploader.
Include the attachment as normal:
class User < ApplicationRecord
include LicenseUploader::Attachment(:license)
end
And encrypt in a controller (or background job, etc) with:
license = params.require(:user).fetch(:license)
lockbox = Lockbox.new(key: Lockbox.attribute_key(table: "users", attribute: "license"))
user.license = lockbox.encrypt_io(license)
To serve encrypted files, use a controller action.
def license
user = User.find(params[:id])
lockbox = Lockbox.new(key: Lockbox.attribute_key(table: "users", attribute: "license"))
send_data lockbox.decrypt(user.license.read), type: user.license.mime_type
end
Use filename
to specify a filename or disposition: "inline"
to show inline.
Generate a key
key = Lockbox.generate_key
Create a lockbox
lockbox = Lockbox.new(key: key)
Encrypt files before passing them to Shrine
LicenseUploader.upload(lockbox.encrypt_io(file), :store)
And decrypt them after reading
lockbox.decrypt(uploaded_file.read)
Generate a key
key = Lockbox.generate_key
Create a lockbox
lockbox = Lockbox.new(key: key)
Encrypt
ciphertext = lockbox.encrypt(File.binread("file.txt"))
Decrypt
lockbox.decrypt(ciphertext)
Generate a key
key = Lockbox.generate_key
Create a lockbox
lockbox = Lockbox.new(key: key, encode: true)
Encrypt
ciphertext = lockbox.encrypt("hello")
Decrypt
lockbox.decrypt(ciphertext)
Use decrypt_str
get the value as UTF-8
To make key rotation easy, you can pass previous versions of keys that can decrypt.
Create config/initializers/lockbox.rb
with:
Lockbox.default_options[:previous_versions] = [{master_key: previous_key}]
To rotate existing Active Record & Mongoid records, use:
Lockbox.rotate(User, attributes: [:email])
To rotate existing Action Text records, use:
Lockbox.rotate(ActionText::RichText, attributes: [:body])
To rotate existing Active Storage files, use:
User.with_attached_license.find_each do |user|
user.license.rotate_encryption!
end
To rotate existing CarrierWave files, use:
User.find_each do |user|
user.license.rotate_encryption!
# or for multiple files
user.licenses.map(&:rotate_encryption!)
end
Once everything is rotated, you can remove previous_versions
from the initializer.
You can also pass previous versions to individual fields and files.
class User < ApplicationRecord
has_encrypted :email, previous_versions: [{master_key: previous_key}]
end
To rotate local files and strings, use:
Lockbox.new(key: key, previous_versions: [{key: previous_key}])
It’s a good idea to track user and employee access to sensitive data. Lockbox provides a convenient way to do this with Active Record, but you can use a similar pattern to write audits to any location.
rails generate lockbox:audits
rails db:migrate
Then create an audit wherever a user can view data:
class UsersController < ApplicationController
def show
@user = User.find(params[:id])
LockboxAudit.create!(
subject: @user,
viewer: current_user,
data: ["name", "email"],
context: "#{controller_name}##{action_name}",
ip: request.remote_ip
)
end
end
Query audits with:
LockboxAudit.last(100)
Note: This approach is not intended to be used in the event of a breach or insider attack, as it’s trivial for someone with access to your infrastructure to bypass.
This is the default algorithm. It’s:
- well-studied
- NIST recommended
- an IETF standard
- fast thanks to a dedicated instruction set
Lockbox uses 256-bit keys.
For users who do a lot of encryptions: You should rotate an individual key after 2 billion encryptions to minimize the chance of a nonce collision, which will expose the authentication key. Each database field and file uploader use a different key (derived from the master key) to extend this window.
You can also use XSalsa20, which uses an extended nonce so you don’t have to worry about nonce collisions. First, install Libsodium. It comes preinstalled on Heroku. For Homebrew, use:
brew install libsodium
And for Ubuntu, use:
sudo apt-get install libsodium23
Then add to your Gemfile:
gem "rbnacl"
And add to your model:
class User < ApplicationRecord
has_encrypted :email, algorithm: "xsalsa20"
end
Make it the default with:
Lockbox.default_options[:algorithm] = "xsalsa20"
You can also pass an algorithm to previous_versions
for key rotation.
Hybrid cryptography allows servers to encrypt data without being able to decrypt it.
Follow the instructions above for installing Libsodium and including rbnacl
in your Gemfile.
Generate a key pair with:
Lockbox.generate_key_pair
Store the keys with your other secrets. Then use:
class User < ApplicationRecord
has_encrypted :email, algorithm: "hybrid", encryption_key: encryption_key, decryption_key: decryption_key
end
Make sure decryption_key
is nil
on servers that shouldn’t decrypt.
This uses X25519 for key exchange and XSalsa20 for encryption.
Lockbox supports a few different ways to set keys for database fields and files.
- Master key
- Per field/uploader
- Per record
By default, the master key is used to generate unique keys for each field/uploader. This technique comes from CipherSweet. The table name and column/uploader name are both used in this process.
You can get an individual key with:
Lockbox.attribute_key(table: "users", attribute: "email_ciphertext")
To rename a table with encrypted columns/uploaders, use:
class User < ApplicationRecord
has_encrypted :email, key_table: "original_table"
end
To rename an encrypted column itself, use:
class User < ApplicationRecord
has_encrypted :email, key_attribute: "original_column"
end
To set a key for an individual field/uploader, use a string:
class User < ApplicationRecord
has_encrypted :email, key: ENV["USER_EMAIL_ENCRYPTION_KEY"]
end
Or a proc:
class User < ApplicationRecord
has_encrypted :email, key: -> { code }
end
To use a different key for each record, use a symbol:
class User < ApplicationRecord
has_encrypted :email, key: :some_method
end
Or a proc:
class User < ApplicationRecord
has_encrypted :email, key: -> { some_method }
end
You can use a key management service to manage your keys with KMS Encrypted.
For Active Record and Mongoid, use:
class User < ApplicationRecord
has_encrypted :email, key: :kms_key
end
For Action Text, use:
ActiveSupport.on_load(:action_text_rich_text) do
ActionText::RichText.has_kms_key
end
Lockbox.encrypts_action_text_body(key: :kms_key)
For Active Storage, use:
class User < ApplicationRecord
encrypts_attached :license, key: :kms_key
end
For CarrierWave, use:
class LicenseUploader < CarrierWave::Uploader::Base
encrypt key: -> { model.kms_key }
end
Note: KMS Encrypted’s key rotation does not know to rotate encrypted files, so avoid calling record.rotate_kms_key!
on models with file uploads for now.
While encryption hides the content of a message, an attacker can still get the length of the message (since the length of the ciphertext is the length of the message plus a constant number of bytes).
Let’s say you want to encrypt the status of a candidate’s background check. Valid statuses are clear
, consider
, and fail
. Even with the data encrypted, it’s trivial to map the ciphertext to a status.
lockbox = Lockbox.new(key: key)
lockbox.encrypt("fail").bytesize # 32
lockbox.encrypt("clear").bytesize # 33
lockbox.encrypt("consider").bytesize # 36
Add padding to conceal the exact length of messages.
lockbox = Lockbox.new(key: key, padding: true)
lockbox.encrypt("fail").bytesize # 44
lockbox.encrypt("clear").bytesize # 44
lockbox.encrypt("consider").bytesize # 44
The block size for padding is 16 bytes by default. Lockbox uses ISO/IEC 7816-4 padding, which uses at least one byte, so if we have a status larger than 15 bytes, it will have a different length than the others.
box.encrypt("length15status!").bytesize # 44
box.encrypt("length16status!!").bytesize # 60
Change the block size with:
Lockbox.new(padding: 32) # bytes
You can pass extra context during encryption to make sure encrypted data isn’t moved to a different context.
lockbox = Lockbox.new(key: key)
ciphertext = lockbox.encrypt(message, associated_data: "somecontext")
Without the same context, decryption will fail.
lockbox.decrypt(ciphertext, associated_data: "somecontext") # success
lockbox.decrypt(ciphertext, associated_data: "othercontext") # fails
You can also use it with database fields and files.
class User < ApplicationRecord
has_encrypted :email, associated_data: -> { code }
end
You can use binary
columns for the ciphertext instead of text
columns.
class AddEmailCiphertextToUsers < ActiveRecord::Migration[8.0]
def change
add_column :users, :email_ciphertext, :binary
end
end
Disable Base64 encoding to save space.
class User < ApplicationRecord
has_encrypted :email, encode: false
end
or set it globally:
Lockbox.encode_attributes = false
It’s easy to read encrypted data in another language if needed.
For AES-GCM, the format is:
- nonce (IV) - 12 bytes
- ciphertext - variable length
- authentication tag - 16 bytes
Here are some examples.
For XSalsa20, use the appropriate Libsodium library.
Lockbox makes it easy to migrate from another library without downtime. The example below uses attr_encrypted
but the same approach should work for any library.
Let’s suppose your model looks like this:
class User < ApplicationRecord
attr_encrypted :name, key: key
attr_encrypted :email, key: key
end
Create a migration with:
class MigrateToLockbox < ActiveRecord::Migration[8.0]
def change
add_column :users, :name_ciphertext, :text
add_column :users, :email_ciphertext, :text
end
end
And add has_encrypted
to your model with the migrating
option:
class User < ApplicationRecord
has_encrypted :name, :email, migrating: true
end
Then run:
Lockbox.migrate(User)
Once all records are migrated, remove the migrating
option and the previous model code (the attr_encrypted
methods in this example).
class User < ApplicationRecord
has_encrypted :name, :email
end
Then remove the previous gem from your Gemfile and drop its columns.
class RemovePreviousEncryptedColumns < ActiveRecord::Migration[8.0]
def change
remove_column :users, :encrypted_name, :text
remove_column :users, :encrypted_name_iv, :text
remove_column :users, :encrypted_email, :text
remove_column :users, :encrypted_email_iv, :text
end
end
View the changelog
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, install Libsodium and run:
git clone https://github.com/ankane/lockbox.git
cd lockbox
bundle install
bundle exec rake test
For security issues, send an email to the address on this page.