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`