README.md in symmetric-encryption-0.2.0 vs README.md in symmetric-encryption-0.3.0

- old
+ new

@@ -131,48 +131,105 @@ # # Symmetric Encryption for Ruby # --- - # Just use test symmetric encryption keys in the development environment - # No private key required since we are not reading the keys from a file + # 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 - cipher: aes-256-cbc symmetric_key: 1234567890ABCDEF1234567890ABCDEF symmetric_iv: 1234567890ABCDEF + encoding: base64 + cipher: aes-128-cbc test: <<: *development_defaults - release: &release_defaults + 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 # - # To generate a new RSA private 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----- - ... - paste RSA key generated above here - ... + 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----- - # Filename containing Symmetric Encryption Key - # Note: The file contents must be RSA 2048 bit encrypted - # with the public key derived from the private key above - symmetric_key_filename: /etc/rails/.rails.key - symmetric_iv_filename: /etc/rails/.rails.iv + # List Symmetric Key files in the order of current / latest first + files: + - + # Filename containing Symmetric Encryption Key encrypted using the + # RSA public key derived from the private key above + symmetric_key_filename: /etc/rails/.rails.key + symmetric_iv_filename: /etc/rails/.rails.iv - # Use aes-256-cbc encryption - cipher: aes-256-cbc + # By adding a version indicator all encrypted data will include + # an additional first Byte that includes this version number to + # assist with speeding up decryption when adding new encryption keys + # and to support old data decryption using older keys + # + # By not specifying a version, or setting it to 0 will disable version + # identification prior to decrypting data + # During decryption these Keys will be tried in the order listed in the + # configuration file starting with the first in the list + # Slower since a decryption attempt is made for every key until the + # correct key is located. However, all encrypted data does not require + # the 1 Byte version header prefix + # + # Default: 0 + version: 0 - hotfix: - <<: *release_defaults + # Set the way the encrypted data is encoded: + # base64 + # Encrypted data is returned in base64 encoding format + # Symmetric::Encryption.decrypt will also base64 decode any data prior + # to decrypting it + # binary + # Encrypted data is returned as raw binary + # Although smaller than base64 it cannot be stored in MySQL text columns + # It can only be held in binary columns such as BINARY or BLOB + # Default: base64 + encoding: base64 - production: - <<: *release_defaults + # 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. @@ -209,92 +266,182 @@ require 'symmetric-encryption' Symmetric::Encryption.load!('config/symmetric-encryption.yml', 'production') Parameters: + * Filename of the configuration file created above * Name of the environment to load the configuration for To manually generate the symmetric encryption keys, run the code below require 'symmetric-encryption' Symmetric::Encryption.generate_symmetric_key_files('config/symmetric-encryption.yml', 'production') Parameters: + * Filename of the configuration file created above * Name of the environment to load the configuration for ## Supporting Multiple Encryption Keys -For complete PCI compliance it is necessary to change the Symmetric Encryption -keys every year. During the transition period of moving from one encryption -key to another symmetric-encryption supports multiple Symmetric Encryption keys. -If decryption with the current key fails, any previous keys will also be tried -automatically. +According to the PCI Compliace documentation: "Cryptographic keys must be changed on an annual basis." +During the transition period of moving from one encryption key to another +symmetric-encryption supports multiple Symmetric Encryption keys. If decryption +with the current key fails, any previous keys will also be tried automatically. + By default the latest key is used for encrypting data. Another key can be specified for encryption so that old data can be looked in queries, etc. Since just the Symmetric Encryption keys are being changed, we can still continue to use the same RSA Private key for gaining access to the Symmetric Encryption Keys ### Configuring multiple Symmetric Encryption keys - - Create a configuration file in config/symmetric-encryption.yml per the following example: # # Symmetric Encryption for Ruby # --- - # Just use test symmetric encryption keys in the development environment - # No private key required since we are not reading the keys from a file + # 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 - cipher: aes-256-cbc symmetric_key: 1234567890ABCDEF1234567890ABCDEF symmetric_iv: 1234567890ABCDEF + encoding: base64 + cipher: aes-128-cbc test: <<: *development_defaults - release: &release_defaults + 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 # - # To generate a new RSA private 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----- - ... - paste RSA key generated above here - ... + 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----- - # Filename containing Symmetric Encryption Key - # Note: The file contents must be RSA 2048 bit encrypted - # with the public key derived from the private key above - symmetric_key_filename: /etc/rails/.rails.key - symmetric_iv_filename: /etc/rails/.rails.iv + # List Symmetric Key files in the order of current / latest first + files: + - + # Filename containing Symmetric Encryption Key encrypted using the + # RSA public key derived from the private key above + symmetric_key_filename: /etc/rails/.rails.key + symmetric_iv_filename: /etc/rails/.rails.iv - # Use aes-256-cbc encryption - cipher: aes-256-cbc + # By adding a version indicator all encrypted data will include + # an additional first Byte that includes this version number to + # assist with speeding up decryption when adding new encryption keys + # and to support old data decryption using older keys + # + # By not specifying a version, or setting it to 0 will disable version + # identification prior to decrypting data + # During decryption these Keys will be tried in the order listed in the + # configuration file starting with the first in the list + # Slower since a decryption attempt is made for every key until the + # correct key is located. However, all encrypted data does not require + # the 1 Byte version header prefix + # + # Default: 0 + version: 0 - hotfix: - <<: *release_defaults + # Set the way the encrypted data is encoded: + # base64 + # Encrypted data is returned in base64 encoding format + # Symmetric::Encryption.decrypt will also base64 decode any data prior + # to decrypting it + # binary + # Encrypted data is returned as raw binary + # Although smaller than base64 it cannot be stored in MySQL text columns + # It can only be held in binary columns such as BINARY or BLOB + # Default: base64 + encoding: base64 - production: - <<: *release_defaults + # 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 + + - + # OPTIONAL: + # + # Any previous Symmetric Encryption Keys + # + # Only used when old data still exists that requires old decryption keys + # to be used + symmetric_key_filename: /etc/rails/.rails_old.key + symmetric_iv_filename: /etc/rails/.rails_old.iv + version: 0 + encoding: base64 + cipher: aes-256-cbc +## Possible Future Enhancements +Submit an issue ticket to request any of the following features: +* Ability to entirely disable encryption for a specific environment. + Symmetric::Encryption.encrypt() would return the supplied data without encrypting it and + Symmetric::Encryption.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 Symmetric::Encryption 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` * Home: <https://github.com/ClarityServices/symmetric-encryption> -* Bugs: <http://github.com/ClarityServices/symmetric-encryption/issues> +* Issues: <http://github.com/ClarityServices/symmetric-encryption/issues> * Gems: <http://rubygems.org/gems/symmetric-encryption> This project uses [Semantic Versioning](http://semver.org/). Authors