Securing User Emails in Rails with Lockbox

Model Code


This is an update to Securing User Emails in Rails with a number of improvements:


Email addresses are a common form of personal data, and they’re often stored unencrypted. If an attacker gains access to the database or backups, emails will be compromised.

This post will walk you through a practical approach to protecting emails. It works with Devise, the most popular authentication framework for Rails, and is general enough to work with others.

Strategy

We’ll use two concepts to make this happen: encryption and blind indexing. Encryption gives us a way to securely store the data, and blind indexing provides a way to look it up.

Blind indexing works by computing a hash of the data. You’re probably familiar with hash functions like MD5 and SHA1. Rather than one of these, we use a hash function that takes a secret key and uses key stretching to slow down brute force attempts. You can read more about blind indexing here.

We’ll use the Lockbox gem for encryption and the Blind Index gem for blind indexing.

Instructions

Let’s assume you have a User model with an email field.

Add to your Gemfile:

gem 'lockbox'
gem 'blind_index'

And run:

bundle install

Generate an 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 variables with your key (you can use this one in development)

LOCKBOX_MASTER_KEY=0000000000000000000000000000000000000000000000000000000000000000
BLIND_INDEX_MASTER_KEY=0000000000000000000000000000000000000000000000000000000000000000

or create config/initializers/lockbox.rb with something like

Lockbox.master_key = Rails.application.credentials.lockbox_master_key
BlindIndex.master_key = Lockbox.master_key

Next, let’s replace the email field with an encrypted version. Create a migration:

rails generate migration add_email_ciphertext_to_users

And add:

class AddEmailCiphertextToUsers < ActiveRecord::Migration[5.2]
  def change
    # encrypted data
    add_column :users, :email_ciphertext, :string

    # blind index
    add_column :users, :email_bidx, :string
    add_index :users, :email_bidx, unique: true

    # drop original here unless we have existing users
    remove_column :users, :email
  end
end

Then migrate:

rails db:migrate

Add to your user model:

class User < ApplicationRecord
  encrypts :email
  blind_index :email
end

Create a new user and confirm it works.

Existing Users

If you have existing users, we need to backfill the data before dropping the email column.

class User < ApplicationRecord
  encrypts :email, migrating: true
  blind_index :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
  encrypts :email
  blind_index :email

  # remove this line after dropping email column
  self.ignored_columns = ["email"]
end

Finally, drop the email column.

Reconfirmable

If you use the confirmable module with reconfirmable, you should also encrypt the unconfirmed_email field.

class AddUnconfirmedEmailToUsers < ActiveRecord::Migration[5.2]
  def change
    add_column :users, :unconfirmed_email_ciphertext, :text
  end
end

And add unconfirmed_email to the list of encrypted fields.

class User < ApplicationRecord
  encrypts :email, :unconfirmed_email
end

Logging

We also need to make sure email addresses aren’t logged. Add to config/initializers/filter_parameter_logging.rb:

Rails.application.config.filter_parameters += [:email]

Use Logstop to filter anything that looks like an email address as an extra line of defense. Add to your Gemfile:

gem 'logstop'

And create config/initializers/logstop.rb with:

Logstop.guard(Rails.logger)

Summary

We now have a way to encrypt emails and query for exact matches. You can apply this same approach to other fields as well. For more security, consider a key management service to manage your keys.

Published July 10, 2019 · Tweet


You might also enjoy

Blind Index 1.0

Hardening Devise

Ruby with OpenSSL 1.1


All code examples are public domain.
Use them however you’d like (licensed under CC0).