Symmetric Encryption

Encrypt data at rest in Ruby and Rails, with keys held outside your source code.

• Active Record attributes and Mongoid fields.
• Passwords in database.yml and other configuration files.
• Entire files and streams, of any size, without loading them into memory.
• Keys in a keystore: a file, an environment variable, AWS KMS, or Google Cloud KMS.
• Key rotation without downtime, since every encrypted value records which key encrypted it.

Documentation: encryption.reidmorrison.com

Do you need it?

Rails 7 added Active Record encryption. If everything you need to encrypt is an Active Record attribute, use that instead. It is built in, and it is maintained by the Rails team.

This gem covers what it does not: Mongoid fields, whole files and streams, standalone Ruby, passwords decrypted before Rails has finished booting, keys held in a cloud KMS, and rotating the key of a value that has to stay queryable. See Do you need it? for the full comparison.

Quick start

gem "symmetric-encryption"

Generate a configuration file and a key for every environment:

symmetric-encryption --generate --app-name my_app

Encrypt an Active Record attribute. The column is a string, since the encrypted value is text:

class Person < ActiveRecord::Base
  attribute :ssn, :encrypted
end

person = Person.create!(name: "Jack", ssn: "123456789")
person.ssn
# => "123456789"

Continue with the Guide, which builds up from here one step at a time.

Documentation

• Guide — the library, one step at a time.
• Configuration — the configuration file and every keystore.
• Rails — encrypted Active Record attributes.
• Mongoid — encrypted Mongoid fields.
• Files — encrypted files and streams.
• Command Line — the symmetric-encryption command.
• Key Rotation — introducing a new key without downtime.
• Security — authenticated encryption and PCI compliance.
• Upgrading — what changes between major versions.
• API — the method reference.

Supported versions

Ruby 3.2 or later, and Rails 7.2 or later when used with Rails. Upgrading from an earlier version of this gem? See Upgrading.

Sister projects

IOStreams is a streaming library that makes compression, encryption, file format, and storage location transparent to your code. It has direct support for Symmetric Encryption, so a file name ending in .enc is encrypted or decrypted with the configuration this gem already loaded. Reach for it when encryption is one step in a larger pipeline:

IOStreams.path("s3://my-bucket/customers.csv.gz.enc").each(:hash) do |record|
  puts record["name"]
end

See Files and Streams for when to use IOStreams and when SymmetricEncryption::Writer and SymmetricEncryption::Reader are enough on their own.

Rocket Job is Ruby's missing batch system. It fully supports Symmetric Encryption to encrypt data in flight and at rest while running jobs in the background.

Author

Reid Morrison

Contributors

Versioning

This project uses Semantic Versioning.

Disclaimer

Although this library has assisted in meeting PCI Compliance and has passed previous PCI audits, it in no way guarantees that PCI Compliance will be achieved by anyone using this library.