AttrCipher

AttrCipher provides functionality to store encrypted attributes in ActiveRecord models. Values are encrypted and decrypted transparently.

Using the same secret for both encryption of plaintext and decryption of ciphertext, AttrCipher uses a method that is known as a symmetric-key algorithm, specifically the Advanced Encryption Standard Cipher-Block Chaining algorithm with a 256bit key (AES-256-CBC). However, you can provide your own cipher algorithm to AttrCipher, if you prefer. As a side note, 256bit AES is what the United States government uses to encrypt information at the Top Secret level.

Installation

To install add the following line to your Gemfile:

gem 'attr_cipher'

And run bundle install.

Dependencies

Runtime:

activerecord (>= 4.2.6)
activesupport (>= 4.2.6)

Development/Test:

rake (~> 10.5)
rspec (~> 3.4)
sqlite3 (~> 1.3)
simplecov (~> 0.11.2)
factory_girl (~> 4.5)

Compatibility

Tested with Ruby 2.3.1p112 (2016-04-26 revision 54768) [x86_64-darwin15] against ActiveRecord 5.0.0 on macOS Sierra 10.12.4 (16E195).

AttrCipher uses OpenSSL to perform the cipher.

Usage

AttrCipher uses a global secret by default and it must be at least 100 characters or more. You can set the secret by setting AttrCipher.secret; (e.g. $ openssl rand -hex 50).

AttrCipher.secret = ENV['SECRET_KEY']

You can also set the secret on a per attribute basis.

class User
  attr_cipher :api_key, secret: ENV['USER_API_KEY_SECRET']
end

Add the attribute as a column to your ActiveRecord migration with _cipher appended to the attribute name:

ActiveRecord::Schema.define do
  create_table :users do |t|
    t.text :api_key_cipher
  end
end

Attributes to be encrypted are declared using the attr_cipher class method in your model:

class User < ActiveRecord::Base
  attr_cipher :api_key
end

In the above example, AttrCipher automatically creates the #api_key getter and #api_key= setter. The getter automatically decrypts the return value. The setter encrypts the value provided and stores it in the api_key_cipher column.

If you don't want to use the AES-256-CBC cipher, you can provide your own cipher object. Define an object that responds to encrypt(secret, value) and decrypt(secret, value) class methods:

module CustomCipher
  def self.encrypt(secret, value)
    value.to_s.reverse
  end
  def self.decrypt(secret, value)
    value.to_s.reverse
  end
end

Then pass the custom cipher object to the cipher option of the attr_cipher class method:

class User < ActiveRecord::Base
  attr_cipher :api_key, cipher: CustomCipher
end

Tests

Tests are written using Rspec, FactoryGirl and Sqlite3. There are 13 examples with 100% code coverage.

To run the tests, execute the default rake task:

bundle exec rake

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Credit

I would like to thank Nando Vieira for his encrypt_attr gem from which some of the code was derived. The encrypt_attr gem is a better fit for non-ActiveRecord use.

This gem was written and is maintained by Jurgen Jocubeit, CEO and President Brightcommerce, Inc.

License

The gem is available as open source under the terms of the MIT License.