Configuring a standalone Symmetric Encryption v3 installation

SymmetricEncryption can also be used standalone and in non-Rails environments.

Install SymmetricEncryption

gem install symmetric-encryption

Give it a try

To tryout Symmetric Encryption standalone and without generating any configuration files or keys yet:

Open an irb console and run the following code:

require 'symmetric-encryption'
# Test cipher
SymmetricEncryption.cipher = SymmetricEncryption::Cipher.new(
  cipher_name: 'aes-128-cbc',
  key:         '1234567890ABCDEF',
  iv:          '1234567890ABCDEF',
  encoding:    :base64strict
)

encrypted = SymmetricEncryption.encrypt 'Hello World'

# => "NIuPIXv/ii1IP1dF6T0NpQ=="

SymmetricEncryption.decrypt(encrypted)

# => "Hello World"

Create configuration file

Manually create a symmetric-encryption.yml configuration file based on the one supplied in examples/symmetric-encryption.yml.

TODO: Add a command to generate a new stand-alone config file

Development use

The configuration file above can be used immediately for development and testing purposes as follows:

require 'symmetric-encryption'
SymmetricEncryption.load!('symmetric-encryption.yml', 'development')

encrypted = SymmetricEncryption.encrypt 'Hello World'

SymmetricEncryption.decrypt(encrypted)

Parameters:

Save to version control

The configuration file should be checked into the source code control system. It does Not include the Symmetric Encryption keys themselves.

Generate production keys

First edit the symmetric-encryption.yml configuration file and specify a writable directory where the files can be written to.

It is recommended that the step below be run on only one of the production servers. The generated key files must then be copied to all the production servers.

Make sure that the current user has read and write access to the folder listed in the config file option key_filename and iv_filename.

To generate the symmetric encryption keys, run the code below in an irb console:

require 'symmetric-encryption'
SymmetricEncryption.generate_symmetric_key_files('symmetric-encryption.yml', 'production')

Parameters:

Notes

Securing the Symmetric Encryption production key files

The encryption key files must not be checked into the source control system and must be distributed and managed separately from the source code.

The symmetric encryption key consists of the key itself and an optional initialization vector.

Once the Symmetric Encryption keys have been generated, secure them further by making the files read-only to the user under which your application will be running and not readable by any other user. Change ownership of the keys to your user and only give it access to read the key files:

In the example below, the application will run under the username jblogs

chown jblogs ~/jblogs/.keys/*
chmod 0400 ~/jblogs/.keys/*

Change jblogs above to the userid under which your Ruby processes are run and update the path to the one supplied in the config file.

When running Ruby servers in a particular environment copy the same key files to every server in that environment. I.e. All Ruby servers in each environment must run the same encryption keys.

Next => Key Rotation