Symmetric Encryption for Ruby Projects using OpenSSL
Transparently encrypt ActiveRecord, Mongoid, and MongoMapper attributes. Encrypt passwords in configuration files. Encrypt entire files at rest.
Any project that wants to meet PCI compliance has to ensure that the data is encrypted whilst in flight and at rest. Amongst many other requirements all passwords in configuration files also have to be encrypted.
Symmetric Encryption helps achieve compliance by supporting encryption of data in a simple and consistent way.
Symmetric Encryption uses OpenSSL to encrypt and decrypt data, and can therefore expose all the encryption algorithms supported by OpenSSL.
Checkout the sister project Rocket Job: Ruby's missing batch system.
Fully supports Symmetric Encryption to encrypt data in flight and at rest while running jobs in the background.
Version 4 of Symmetric Encryption has completely adopted the Ruby keyword arguments on most API's where multiple arguments are being passed, or where a Hash was being used before.
The encrypt and decrypt API now require keyword arguments for any optional arguments.
The following does not change:
encrypted = SymmetricEncryption.encrypt('Hello World') SymmetricEncryption.decrypt(encrypted)
The following is not backward compatible: ~~~ruby SymmetricEncryption.encrypt('Hello World', false, false, :date) ~~~
Needs to be changed to: ~~~ruby SymmetricEncryption.encrypt('Hello World', random_iv: false, compress: false, type: :date) ~~~
Or, just to change the type: ~~~ruby SymmetricEncryption.encrypt('Hello World', type: :date) ~~~
decryptapi has also changed: ~~~ruby SymmetricEncryption.decrypt(encrypted, 2, :date) ~~~
Needs to be changed to: ~~~ruby SymmetricEncryption.decrypt(encrypted, version: 2, type: :string) ~~~
The Rake tasks have been replaced with a new command line interface for managing key configuration and generation. For more info: ~~~ symmetric-encryption --help ~~~
In Symmetric Encryption V4 the configuration file is now modified directly instead of using templates. This change is necessary to allow the command line interface to generate new keys and automatically update the configuration file.
Please backup your existing
symmetric-encryption.ymlprior to upgrading if it is not already in a version control system. This is critical for configurations that have custom code or for prior configurations targeting heroku.
In Symmetric Encryption V4 the defaults for
always_add_headerhave changed. If these values are not explicitly set in the
symmetric-encryption.ymlfile, set them prior to upgrading.
Prior defaults, set explicitly to these values if missing for all environments: ~~~yaml encoding: :base64 alwaysaddheader: false ~~~
New defaults are: ~~~yaml encoding: :base64strict alwaysaddheader: true ~~~
In version 3 of SymmetricEncryption, the following changes have been made that may have backward compatibility issues:
SymmetricEncryption.decryptno longer rotates through all the decryption keys when previous ciphers fail to decrypt the encrypted string. In a very small, yet significant number of cases it was possible to decrypt data using the incorrect key. Clearly the data returned was garbage, but it still returned a string of data instead of throwing an exception. See
SymmetricEncryption.select_cipherto supply your own custom logic to determine the correct cipher to use when the encrypted string does not have a header and multiple ciphers are defined.
Configuration file format prior to V1 is no longer supported.
New configuration option has been added to support setting encryption keys from environment variables.
Cipher.parse_magic_header!now returns a Struct instead of an Array.
New config options
:encrypted_ivto support setting the encryption key in environment variables, or from other sources such as ldap or a central directory service.
Ability to randomly generate a new initialization vector (iv) with every encryption and put the iv in the encrypted data as its header, without having to use
With file encryption randomly generate a new key and initialization vector (iv) with every file encryption and put the key and iv in the encrypted data as its header which is encrypted using the global key and iv.
Support for compression.
SymmetricEncryption.encrypthas two additional optional parameters:
This project uses Semantic Versioning.
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.