README.md in symmetric-encryption-0.7.2 vs README.md in symmetric-encryption-0.8.0
- old
+ new
@@ -136,135 +136,102 @@
specified environment
Note: Passwords must be encrypted in the environment in which they will be used.
Since each environment should have its own symmetric encryption keys
-## Install
+## Installation
- gem install symmetric-encryption
+### Add to an existing Rails project
+Add the following line to Gemfile
-## Configuration
+ gem 'symmetric-encryption'
-### Generating the RSA Private key
+Install the Gem with bundler
-To protect the files holding the Symmetric Encryption keys, symmetric-encryption uses 2048 bit RSA
-encryption.
+ bundle install
-Generate the RSA Private key as follows
+## Rails Configuration
- openssl genrsa 2048
-
-Paste the output into the configuration created below
-
### Creating the configuration file
-Create a configuration file in config/symmetric-encryption.yml per the following example:
+The configuration file contains the path to the production encryption key files.
+Generally in development and test the files are not created, so supply the full path
+to these files in production. Once the config file has been generated it can be
+modified as needed.
- #
- # Symmetric Encryption for Ruby
- #
- ---
- # For the development and test environments the test symmetric encryption keys
- # can be placed directly in the source code.
- # And therefore no RSA private key is required
- development: &development_defaults
- key: 1234567890ABCDEF1234567890ABCDEF
- iv: 1234567890ABCDEF
- cipher: aes-128-cbc
+Generate the configuration file:
- test:
- <<: *development_defaults
+ rails generate symmetric_encryption:config /etc/rails/keys
- production:
- # Since the key to encrypt and decrypt with must NOT be stored along with the
- # source code, we only hold a RSA key that is used to unlock the file
- # containing the actual symmetric encryption key
- #
- # Sample RSA Key, DO NOT use this RSA key, generate a new one using
- # openssl genrsa 2048
- private_rsa_key: |
- -----BEGIN RSA PRIVATE KEY-----
- MIIEpAIBAAKCAQEAxIL9H/jYUGpA38v6PowRSRJEo3aNVXULNM/QNRpx2DTf++KH
- 6DcuFTFcNSSSxG9n4y7tKi755be8N0uwCCuOzvXqfWmXYjbLwK3Ib2vm0btpHyvA
- qxgqeJOOCxKdW/cUFLWn0tACUcEjVCNfWEGaFyvkOUuR7Ub9KfhbW9cZO3BxZMUf
- IPGlHl/gWyf484sXygd+S7cpDTRRzo9RjG74DwfE0MFGf9a1fTkxnSgeOJ6asTOy
- fp9tEToUlbglKaYGpOGHYQ9TV5ZsyJ9jRUyb4SP5wK2eK6dHTxTcHvT03kD90Hv4
- WeKIXv3WOjkwNEyMdpnJJfSDb5oquQvCNi7ZSQIDAQABAoIBAQCbzR7TUoBugU+e
- ICLvpC2wOYOh9kRoFLwlyv3QnH7WZFWRZzFJszYeJ1xr5etXQtyjCnmOkGAg+WOI
- k8GlOKOpAuA/PpB/leJFiYL4lBwU/PmDdTT0cdx6bMKZlNCeMW8CXGQKiFDOcMqJ
- 0uGtH5YD+RChPIEeFsJxnC8SyZ9/t2ra7XnMGiCZvRXIUDSEIIsRx/mOymJ7bL+h
- Lbp46IfXf6ZuIzwzoIk0JReV/r+wdmkAVDkrrMkCmVS4/X1wN/Tiik9/yvbsh/CL
- ztC55eSIEjATkWxnXfPASZN6oUfQPEveGH3HzNjdncjH/Ho8FaNMIAfFpBhhLPi9
- nG5sbH+BAoGBAOdoUyVoAA/QUa3/FkQaa7Ajjehe5MR5k6VtaGtcxrLiBjrNR7x+
- nqlZlGvWDMiCz49dgj+G1Qk1bbYrZLRX/Hjeqy5dZOGLMfgf9eKUmS1rDwAzBMcj
- M9jnnJEBx8HIlNzaR6wzp3GMd0rrccs660A8URvzkgo9qNbvMLq9vyUtAoGBANll
- SY1Iv9uaIz8klTXU9YzYtsfUmgXzw7K8StPdbEbo8F1J3JPJB4D7QHF0ObIaSWuf
- suZqLsvWlYGuJeyX2ntlBN82ORfvUdOrdrbDlmPyj4PfFVl0AK3U3Ai374DNrjKR
- hF6YFm4TLDaJhUjeV5C43kbE1N2FAMS9LYtPJ44NAoGAFDGHZ/E+aCLerddfwwun
- MBS6MnftcLPHTZ1RimTrNfsBXipBw1ItWEvn5s0kCm9X24PmdNK4TnhqHYaF4DL5
- ZjbQK1idEA2Mi8GGPIKJJ2x7P6I0HYiV4qy7fe/w1ZlCXE90B7PuPbtrQY9wO7Ll
- ipJ45X6I1PnyfOcckn8yafUCgYACtPAlgjJhWZn2v03cTbqA9nHQKyV/zXkyUIXd
- /XPLrjrP7ouAi5A8WuSChR/yx8ECRgrEM65Be3qBEtoGCB4AS1G0NcigM6qhKBFi
- VS0aMXr3+V8argcUIwJaWW/x+p2go48yXlJpLHPweeXe8mXEt4iM+QZte6p2yKQ4
- h9PGQQKBgQCqSydmXBnXGIVTp2sH/2GnpxLYnDBpcJE0tM8bJ42HEQQgRThIChsn
- PnGA91G9MVikYapgI0VYBHQOTsz8rTIUzsKwXG+TIaK+W84nxH5y6jUkjqwxZmAz
- r1URaMAun2PfAB4g2N/kEZTExgeOGqXjFhvvjdzl97ux2cTyZhaTXg==
- -----END RSA PRIVATE KEY-----
+Note: Ignore the warning about "Symmetric Encryption config not found" since it is
+being generated
- # List Symmetric Key files in the order of current / latest first
- ciphers:
- -
- # Filename containing Symmetric Encryption Key encrypted using the
- # RSA public key derived from the private key above
- key_filename: /etc/rails/.rails.key
- iv_filename: /etc/rails/.rails.iv
+#### Save to version control
- # Encryption cipher
- # Recommended values:
- # aes-256-cbc
- # 256 AES CBC Algorithm. Very strong
- # Ruby 1.8.7 MRI Approximately 100,000 encryptions or decryptions per second
- # JRuby 1.6.7 with Ruby 1.8.7 Approximately 22,000 encryptions or decryptions per second
- # aes-128-cbc
- # 128 AES CBC Algorithm. Less strong.
- # Ruby 1.8.7 MRI Approximately 100,000 encryptions or decryptions per second
- # JRuby 1.6.7 with Ruby 1.8.7 Approximately 22,000 encryptions or decryptions per second
- cipher: aes-256-cbc
-
This configuration file should be checked into the source code control system.
It does Not include the Symmetric Encryption keys. They will be generated in the
next step.
### Generating and securing the Symmetric Encryption keys
+Once development and testing is complete we need to generate secure encryption
+key files for production. 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 web servers.
+
+Note: Do not run this step more than once, otherwise new keys will be generated
+and any encrypted data will no longer be accessible.
+
+Note: Do not run this step on more than one server in each environment otherwise
+each server will be encrypting with it's own key and the servers will not be able
+to decrypt data encrypted on another server. Just copy the generated files to each
+server
+
The symmetric encryption key consists of the key itself and an optional
initialization vector.
-To generate the keys run the following Rake task in each environment:
+To generate the keys run the following Rake task once only in each environment:
- RAILS_ENV=production rake symmetric_encryption:generate_symmetric_keys
+ rails generate symmetric_encryption:new_keys production
Replace 'production' as necessary for each environment.
Make sure that the current user has read and write access to the folder listed
-in the configuration option symmetric_key_filename above.
+in the config file option key_filename.
+Note: Ignore the warning about the key files "not found or readable" since they
+are being generated
+
Once the Symmetric Encryption keys have been generated, secure them further by
-making the files read-only to the Rails user and not readable by any other user
+making the files read-only to the Rails user and not readable by any other user.
+Change ownership of the keys to the rails user and only give it access to read the key files:
- chmod ...
+ chown rails /etc/rails/keys/*
+ chmod 0400 /etc/rails/keys/*
+Change 'rails' above to the userid under which your Rails processes are run
+and update the path to the one supplied when generating the config file or
+look in the config file itself
+
When running multiple Rails servers in a particular environment copy the same
key files to every server in that environment. I.e. All Rails servers in each
environment must run the same encryption keys.
Note: The generate step above must only be run once in each environment
## Using in non-Rails environments
-symmetric-encryption can also be used in non-Rails environment. At application
-startup, run the code below to initialize symmetric-encryption prior to
+SymmetricEncryption can also be used in non-Rails environment.
+
+Install SymmetricEncryption
+
+ gem install symmetric-encryption
+
+Manually create a symmetric-encryption.yml configuration file based on the
+one supplied in examples/symmetric-encryption.yml.
+
+At application startup, run the code below to initialize symmetric-encryption prior to
attempting to encrypt or decrypt any data
require 'symmetric-encryption'
SymmetricEncryption.load!('config/symmetric-encryption.yml', 'production')
@@ -307,12 +274,12 @@
---
# For the development and test environments the test symmetric encryption keys
# can be placed directly in the source code.
# And therefore no RSA private key is required
development: &development_defaults
- key: 1234567890ABCDEF1234567890ABCDEF
- iv: 1234567890ABCDEF
+ key: 1234567890ABCDEF1234567890ABCDEF
+ iv: 1234567890ABCDEF
cipher: aes-128-cbc
test:
<<: *development_defaults
@@ -356,11 +323,11 @@
ciphers:
-
# Filename containing Symmetric Encryption Key encrypted using the
# RSA public key derived from the private key above
key_filename: /etc/rails/.rails.key
- iv_filename: /etc/rails/.rails.iv
+ iv_filename: /etc/rails/.rails.iv
# Encryption cipher
# Recommended values:
# aes-256-cbc
# 256 AES CBC Algorithm. Very strong
@@ -378,33 +345,30 @@
# Any previous Symmetric Encryption Keys
#
# Only used when old data still exists that requires old decryption keys
# to be used
key_filename: /etc/rails/.rails_old.key
- iv_filename: /etc/rails/.rails_old.iv
- cipher: aes-256-cbc
+ iv_filename: /etc/rails/.rails_old.iv
+ cipher: aes-256-cbc
-## Possible Future Enhancements
+## Future Enhancements
+* Ability to randomly generate a new initialization vector (iv) with every
+ encryption and put the iv in the encrypted data as its header
+
+* 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
+
Submit an issue ticket to request any of the following features:
* Ability to entirely disable encryption for a specific environment.
SymmetricEncryption.encrypt() would return the supplied data without encrypting it and
SymmetricEncryption.decrypt() would return the supplied data without decrypting it
* Support for automatically compressing data prior to encrypting it when the
data exceeds some predefined size. And automatically decompressing the data
during decryption
-
-* Make attr_encrypted auto-detect the encrypted column type and Base64 encode
- when type is CHAR and store as binary when type is BINARY or BLOB
-
-* Create rake task / generator to generate a sample configuration file
- with a new RSA Private key already in it
-
-* Ability to change SymmetricEncryption configuration options from custom
- Rails initializers, rather than having everything in the config file.
- For example config.symmetric_encryption.cipher = 'aes-128-cbc'
Meta
----
* Code: `git clone git://github.com/ClarityServices/symmetric-encryption.git`