symmetric-encryption 0.2.0 → 0.3.0

data/README.md

@@ -133,44 +133,101 @@ Create a configuration file in config/symmetric-encryption.yml per the following
     # 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
-
-      # Use aes-256-cbc encryption
-      cipher: aes-256-cbc
-
-    hotfix:
-      <<: *release_defaults
-
-    production:
-      <<: *release_defaults
+      # 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
+
+          # 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
+
+          # 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
+
+          # 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
@@ -211,6 +268,7 @@ attempting to encrypt or decrypt any data
     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
 
@@ -220,16 +278,17 @@ To manually generate the symmetric encryption keys, run the code below
     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.
@@ -239,61 +298,149 @@ 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
-
-      # Use aes-256-cbc encryption
-      cipher: aes-256-cbc
-
-    hotfix:
-      <<: *release_defaults
-
-    production:
-      <<: *release_defaults
-
-
+      # 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
+
+          # 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
+
+          # 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
+
+          # 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/).

data/examples/symmetric-encryption.yml

@@ -2,25 +2,24 @@
 # 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
+  symmetric_iv:  1234567890ABCDEF
+  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
-
-  # Sample RSA Key, do not use this one as is, generate a new one
   private_rsa_key: |
     -----BEGIN RSA PRIVATE KEY-----
     MIIEpAIBAAKCAQEAxIL9H/jYUGpA38v6PowRSRJEo3aNVXULNM/QNRpx2DTf++KH
@@ -50,17 +49,63 @@ release: &release_defaults
     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 Ciphers 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
+    - symmetric_key_filename: /etc/rails/.rails.key
+      symmetric_iv_filename: /etc/rails/.rails.iv
 
-  # Use aes-256-cbc encryption
-  cipher: aes-256-cbc
+      # 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
 
-hotfix:
-  <<: *release_defaults
+      # FUTURE ENHANCEMENT:
+      #
+      # 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
 
-production:
-  <<: *release_defaults
+      # FUTURE ENHANCEMENT:
+      #
+      # 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
+
+      # 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
+      cipher:                 aes-256-cbc

data/lib/symmetric/cipher.rb

@@ -0,0 +1,184 @@
+require 'base64'
+require 'openssl'
+require 'zlib'
+
+module Symmetric
+
+  # Hold all information related to encryption keys
+  # as well as encrypt and decrypt data using those keys
+  #
+  # Cipher is thread safe so that the same instance can be called by multiple
+  # threads at the same time without needing an instance of Cipher per thread
+  class Cipher
+    # Cipher to use for encryption and decryption
+    attr_reader :cipher
+
+    # Future Use:
+    # attr_accessor :encoding, :version
+
+    # Generate a new Symmetric Key pair
+    #
+    # Returns a hash containing a new random symmetric_key pair
+    # consisting of a :key and :iv.
+    # The cipher is also included for compatibility with the Cipher initializer
+    def self.random_key_pair(cipher = 'aes-256-cbc', generate_iv = true)
+      openssl_cipher = OpenSSL::Cipher.new(cipher)
+      openssl_cipher.encrypt
+      
+      {
+        :key    => openssl_cipher.random_key,
+        :iv     => generate_iv ? openssl_cipher.random_iv : nil,
+        :cipher => cipher
+      }
+    end
+
+    # Create a Symmetric::Key for encryption and decryption purposes
+    #
+    # Parameters:
+    #   :key
+    #     The Symmetric Key to use for encryption and decryption
+    #   :iv
+    #     Optional. The Initialization Vector to use with Symmetric Key
+    #   :cipher
+    #     Optional. Encryption Cipher to use
+    #     Default: aes-256-cbc
+    def initialize(parms={})
+      raise "Missing mandatory parameter :key" unless @key = parms[:key]
+      @iv = parms[:iv]
+      @cipher = parms[:cipher] || 'aes-256-cbc'
+    end
+
+    # AES Symmetric Encryption of supplied string
+    #  Returns result as a Base64 encoded string
+    #  Returns nil if the supplied str is nil
+    #  Returns "" if it is a string and it is empty
+    def encrypt(str)
+      return str if str.nil? || (str.is_a?(String) && str.empty?)
+      ::Base64.encode64(crypt(:encrypt, str))
+    end
+
+    # AES Symmetric Decryption of supplied string
+    #  Returns decrypted string
+    #  Returns nil if the supplied str is nil
+    #  Returns "" if it is a string and it is empty
+    def decrypt(str)
+      return str if str.nil? || (str.is_a?(String) && str.empty?)
+      crypt(:decrypt, ::Base64.decode64(str))
+    end
+
+    # The minimum length for an encrypted string
+    def min_encrypted_length
+      @min_encrypted_length ||= encrypt('1').length
+    end
+
+    # Returns [true|false] a best effort determination as to whether the supplied
+    # string is encrypted or not, without incurring the penalty of actually
+    # decrypting the supplied data
+    #   Parameters:
+    #     encrypted_data: Encrypted string
+    def encrypted?(encrypted_data)
+      # Simple checks first
+      return false if (encrypted_data.length < min_encrypted_length) || (!encrypted_data.end_with?("\n"))
+      # For now have to decrypt it fully
+      begin
+        decrypt(encrypted_data) ? true : false
+      rescue
+        false
+      end
+    end
+
+    # Return a new random key using the configured cipher
+    # Useful for generating new symmetric keys
+    def random_key
+      ::OpenSSL::Cipher::Cipher.new(@cipher).random_key
+    end
+
+    protected
+
+    # Some of these methods are for future use to handle binary data, etc..
+
+    # Binary encrypted data includes this magic header so that we can quickly
+    # identify binary data versus base64 encoded data that does not have this header
+    unless defined? MAGIC_HEADER
+      MAGIC_HEADER = '@EnC'
+      MAGIC_HEADER_SIZE = MAGIC_HEADER.size
+    end
+
+    # AES Symmetric Encryption of supplied string
+    #  Returns result as a binary encrypted string
+    #  Returns nil if the supplied str is nil or empty
+    # Parameters
+    #  compress => Whether to compress the supplied string using zip before
+    #              encrypting
+    #              true | false
+    #              Default false
+    def self.encrypt_binary(str, compress=false)
+      return nil if str.nil? || (str.is_a?(String) && str.empty?)
+      # Bit Layout
+      # 15    => Compressed?
+      # 0..14 => Version number of encryption key/algorithm currently 0
+      flags = 0 # Same as 0b0000_0000_0000_0000
+      # If the data is to be compressed before being encrypted, set the flag and
+      # compress using zlib. Only compress if data is greater than 15 chars
+      str = str.to_s unless str.is_a?(String)
+      if compress && str.length > 15
+        flags |= 0b1000_0000_0000_0000
+        begin
+          ostream = StringIO.new
+          gz = ::Zlib::GzipWriter.new(ostream)
+          gz.write(str)
+          str = ostream.string
+        ensure
+          gz.close
+        end
+      end
+      return nil unless encrypted = self.crypt(:encrypt, str)
+      # Resulting buffer consists of:
+      #   '@EnC'
+      #   unsigned short (32 bits) in little endian format for flags above
+      #   'actual encrypted buffer data'
+      "#{MAGIC_HEADER}#{[flags].pack('v')}#{encrypted}"
+    end
+
+    # AES Symmetric Decryption of supplied Binary string
+    #  Returns decrypted string
+    #  Returns nil if the supplied str is nil
+    #  Returns "" if it is a string and it is empty
+    def self.decrypt_binary(str)
+      return str if str.nil? || (str.is_a?(String) && str.empty?)
+      str = str.to_s unless str.is_a?(String)
+      encrypted = if str.starts_with? MAGIC_HEADER
+        # Remove header and extract flags
+        header, flags = str.unpack(@@unpack ||= "A#{MAGIC_HEADER_SIZE}v")
+        # Uncompress if data is compressed and remove header
+        if flags & 0b1000_0000_0000_0000
+          begin
+            gz = ::Zlib::GzipReader.new(StringIO.new(str[MAGIC_HEADER_SIZE,-1]))
+            gz.read
+          ensure
+            gz.close
+          end
+        else
+          str[MAGIC_HEADER_SIZE,-1]
+        end
+      else
+        ::Base64.decode64(str)
+      end
+      crypt(:decrypt, encrypted)
+    end
+
+    # Creates a new OpenSSL::Cipher with every call so that this call
+    # is thread-safe
+    def crypt(cipher_method, string) #:nodoc:
+      openssl_cipher = ::OpenSSL::Cipher.new(self.cipher)
+      openssl_cipher.send(cipher_method)
+      raise "Encryption.key must be set before calling Encryption encrypt or decrypt" unless @key
+      openssl_cipher.key = @key
+      openssl_cipher.iv = @iv if @iv
+      result = openssl_cipher.update(string.to_s)
+      result << openssl_cipher.final
+    end
+
+  end
+
+end