symmetric-encryption 1.1.1 → 2.0.0

data/lib/symmetric_encryption/extensions/active_record/base.rb

@@ -2,26 +2,49 @@ module ActiveRecord #:nodoc:
   class Base
 
     class << self # Class methods
-      # Much lighter weight encryption for Rails attributes matching the
-      # attr_encrypted interface using SymmetricEncryption
+      # Drop in replacement for attr_encrypted gem, except that it uses
+      # SymmetricEncryption for managing the encryption key
       #
-      # The regular attr_encrypted gem uses Encryptor that adds encryption to
-      # every Ruby object which is a complete overkill for this simple use-case
-      #
-      # Params:
-      # * symbolic names of each method to create which has a corresponding
+      # Parameters:
+      # * Symbolic names of each method to create which has a corresponding
       #   method already defined in rails starting with: encrypted_
-      # * Followed by an option hash:
-      #      :marshal => Whether this element should be converted to YAML before encryption
-      #                  true or false
-      #                  Default: false
-      #
+      # * Followed by an optional hash:
+      #     :marshal [true|false]
+      #       Whether this element should be converted to YAML before encryption
+      #       Default: false
+      #
+      #     :random_iv [true|false]
+      #       Whether the encrypted value should use a random IV every time the
+      #       field is encrypted.
+      #       It is recommended to set this to true where feasible. If the encrypted
+      #       value could be used as part of a SQL where clause, or as part
+      #       of any lookup, then it must be false.
+      #       Setting random_iv to true will result in a different encrypted output for
+      #       the same input string.
+      #       Note: Only set to true if the field will never be used as part of
+      #         the where clause in an SQL query.
+      #       Note: When random_iv is true it will add a 8 byte header, plus the bytes
+      #         to store the random IV in every returned encrypted string, prior to the
+      #         encoding if any.
+      #       Default: false
+      #       Highly Recommended where feasible: true
+      #
+      #     :compress [true|false]
+      #       Whether to compress str before encryption
+      #       Should only be used for large strings since compression overhead and
+      #       the overhead of adding the 'magic' header may exceed any benefits of
+      #       compression
+      #       Note: Adds a 6 byte header prior to encoding, only if :random_iv is false
+      #       Default: false
       def attr_encrypted(*params)
         # Ensure ActiveRecord has created all its methods first
         # Ignore failures since the table may not yet actually exist
         define_attribute_methods rescue nil
 
         options = params.last.is_a?(Hash) ? params.pop : {}
+        random_iv = options.fetch(:random_iv, false)
+        compress  = options.fetch(:compress, false)
+        marshal   = options.fetch(:marshal, false)
 
         params.each do |attribute|
           # Generate unencrypted attribute with getter and setter
@@ -40,7 +63,7 @@ module ActiveRecord #:nodoc:
             # Set the un-encrypted attribute
             # Also updates the encrypted field with the encrypted value
             def #{attribute}=(value)
-              self.encrypted_#{attribute} = @stored_encrypted_#{attribute} = ::SymmetricEncryption.encrypt(value#{".to_yaml" if options[:marshal]})
+              self.encrypted_#{attribute} = @stored_encrypted_#{attribute} = ::SymmetricEncryption.encrypt(value#{".to_yaml" if marshal},#{random_iv},#{compress})
               @#{attribute} = value
             end
           UNENCRYPTED

data/lib/symmetric_encryption/extensions/mongoid/fields.rb

@@ -25,6 +25,7 @@ module Mongoid
       #    field :name,                             :type => String
       #    field :encrypted_social_security_number, :type => String, :encrypted => true
       #    field :age,                              :type => Integer
+      #    field :life_history,                     :type => String, :encrypted => true, :compress => true, :random_iv => true
       #
       #  end
       #
@@ -50,28 +51,35 @@ module Mongoid
       #   person.social_security_number = "123456789"
       #
       #   # Or, is equivalent to:
-      #   person.social_security_number = SymmetricEncryption.encrypt("123456789")
+      #   person.encrypted_social_security_number = SymmetricEncryption.encrypt("123456789")
       #
       #
       # Note: Unlike attr_encrypted finders must use the encrypted field name
-      #   For Example this is NOT valid:
+      #   Invalid Example, does not work:
       #     person = Person.where(:social_security_number => '123456789').first
       #
+      #   Valid Example:
+      #     person = Person.where(:encrypted_social_security_number => SymmetricEncryption.encrypt('123456789')).first
+      #
       # Defines all the fields that are accessible on the Document
       # For each field that is defined, a getter and setter will be
       # added as an instance method to the Document.
       #
       # @example Define a field.
-      #   field :score, :type => Integer, :default => 0
+      #   field :social_security_number, :type => String, :encrypted => true, :compress => false, :random_iv => false
+      #   field :sensitive_text, :type => String, :encrypted => true, :compress => true, :random_iv => true
       #
       # @param [ Symbol ] name The name of the field.
       # @param [ Hash ] options The options to pass to the field.
       #
-      # @option options [ Boolean ] :encryption If the field contains encrypted data.
-      # @option options [ Symbol ] :decrypt_as Name of the getters and setters to generate to access the decrypted value of this field.
-      # @option options [ Class ] :type The type of the field.
-      # @option options [ String ] :label The label for the field.
-      # @option options [ Object, Proc ] :default The field's default
+      # @option options [ Boolean ] :encrypted  If the field contains encrypted data.
+      # @option options [ Symbol ]  :decrypt_as Name of the getters and setters to generate to access the decrypted value of this field.
+      # @option options [ Boolean ] :compress   Whether to compress this encrypted field
+      # @option options [ Boolean ] :random_iv  Whether the encrypted value should use a random IV every time the field is encrypted.
+      #
+      # @option options [ Class ]   :type The type of the field.
+      # @option options [ String ]  :label The label for the field.
+      # @option options [ Object, Proc ] :default The fields default
       #
       # @return [ Field ] The generated field
       def field_with_symmetric_encryption(field_name, options={})
@@ -82,20 +90,23 @@ module Mongoid
             decrypt_as = field_name.to_s['encrypted_'.length..-1]
           end
 
+          random_iv = options.delete(:random_iv) || false
+          compress  = options.delete(:compress) || false
+
           # Store Intended data type for this field, but we store it as a String
           underlying_type = options[:type]
           options[:type] = String
 
           raise "SymmetricEncryption for Mongoid currently only supports :type => String" unless underlying_type == String
 
-          # #TODO Need to do type conversions. Currently only support String
+          # #TODO Need to do type conversions. Currently only supports String
 
           # Generate getter and setter methods
           class_eval(<<-EOS, __FILE__, __LINE__ + 1)
-            # Set the un-encrypted bank account number
+            # Set the un-encrypted field
             # Also updates the encrypted field with the encrypted value
             def #{decrypt_as}=(value)
-              @stored_#{field_name} = SymmetricEncryption.encrypt(value)
+              @stored_#{field_name} = ::SymmetricEncryption.encrypt(value,#{random_iv},#{compress})
               self.#{field_name} = @stored_#{field_name}
               @#{decrypt_as} = value
             end
@@ -105,7 +116,7 @@ module Mongoid
             # If this method is not called, then the encrypted value is never decrypted
             def #{decrypt_as}
               if @stored_#{field_name} != self.#{field_name}
-                @#{decrypt_as} = SymmetricEncryption.decrypt(self.#{field_name})
+                @#{decrypt_as} = ::SymmetricEncryption.decrypt(self.#{field_name})
                 @stored_#{field_name} = self.#{field_name}
               end
               @#{decrypt_as}

data/lib/symmetric_encryption/railtie.rb

@@ -10,7 +10,7 @@ module SymmetricEncryption #:nodoc:
     #       config.symmetric_encryption.cipher = SymmetricEncryption::Cipher.new(
     #         :key    => '1234567890ABCDEF1234567890ABCDEF',
     #         :iv     => '1234567890ABCDEF',
-    #         :cipher => 'aes-128-cbc'
+    #         :cipher_name => 'aes-128-cbc'
     #       )
     #     end
     #   end
@@ -26,9 +26,9 @@ module SymmetricEncryption #:nodoc:
     # @example symmetric-encryption.yml
     #
     #   development:
-    #     cipher: aes-256-cbc
-    #     symmetric_key: 1234567890ABCDEF1234567890ABCDEF
-    #     symmetric_iv: 1234567890ABCDEF
+    #     cipher_name: aes-256-cbc
+    #     key:         1234567890ABCDEF1234567890ABCDEF
+    #     iv:          1234567890ABCDEF
     #
     # Loaded before Active Record initializes since database.yml can have encrypted
     # passwords in it

data/lib/symmetric_encryption/reader.rb

@@ -1,3 +1,5 @@
+require 'openssl'
+
 module SymmetricEncryption
   # Read from encrypted files and other IO streams
   #
@@ -293,12 +295,12 @@ module SymmetricEncryption
       buf = @ios.read(@buffer_size)
 
       # Use cipher specified in header, or global cipher if it has no header
-      @cipher, @compressed = SymmetricEncryption::Cipher.parse_magic_header!(buf, @version)
-
-      # Use supplied version if cipher could not be detected due to missing header
-      @cipher ||= SymmetricEncryption.cipher(@version)
+      @compressed, iv, key, cipher_name, decryption_cipher = SymmetricEncryption::Cipher.parse_magic_header!(buf, @version)
 
-      @stream_cipher = @cipher.send(:openssl_cipher, :decrypt)
+      @stream_cipher = ::OpenSSL::Cipher.new(cipher_name || decryption_cipher.cipher_name)
+      @stream_cipher.decrypt
+      @stream_cipher.key = key || decryption_cipher.send(:key)
+      @stream_cipher.iv = iv || decryption_cipher.send(:iv)
 
       # First call to #update should return an empty string anyway
       @read_buffer = @stream_cipher.update(buf)

data/lib/symmetric_encryption/symmetric_encryption.rb

@@ -85,11 +85,40 @@ module SymmetricEncryption
   #  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 self.encrypt(str)
+  #
+  # Parameters
+  #   str [String]
+  #     String to be encrypted. If str is not a string, #to_s will be called on it
+  #     to convert it to a string
+  #
+  #   random_iv [true|false]
+  #     Whether the encypted value should use a random IV every time the
+  #     field is encrypted.
+  #     It is recommended to set this to true where feasible. If the encrypted
+  #     value could be used as part of a SQL where clause, or as part
+  #     of any lookup, then it must be false.
+  #     Setting random_iv to true will result in a different encrypted output for
+  #     the same input string.
+  #     Note: Only set to true if the field will never be used as part of
+  #       the where clause in an SQL query.
+  #     Note: When random_iv is true it will add a 8 byte header, plus the bytes
+  #       to store the random IV in every returned encrypted string, prior to the
+  #       encoding if any.
+  #     Default: false
+  #     Highly Recommended where feasible: true
+  #
+  #   compress [true|false]
+  #     Whether to compress str before encryption
+  #     Should only be used for large strings since compression overhead and
+  #     the overhead of adding the 'magic' header may exceed any benefits of
+  #     compression
+  #     Note: Adds a 6 byte header prior to encoding, only if :random_iv is false
+  #     Default: false
+  def self.encrypt(str, random_iv=false, compress=false)
     raise "Call SymmetricEncryption.load! or SymmetricEncryption.cipher= prior to encrypting or decrypting data" unless @@cipher
 
     # Encrypt and then encode the supplied string
-    @@cipher.encrypt(str)
+    @@cipher.encrypt(str, random_iv, compress)
   end
 
   # Invokes decrypt
@@ -159,13 +188,13 @@ module SymmetricEncryption
     cipher_cfg = config[:ciphers].first
     key_filename = cipher_cfg[:key_filename]
     iv_filename = cipher_cfg[:iv_filename]
-    cipher = cipher_cfg[:cipher]
+    cipher_name = cipher_cfg[:cipher_name] || cipher_cfg[:cipher]
 
     raise "The configuration file must contain a 'private_rsa_key' parameter to generate symmetric keys" unless config[:private_rsa_key]
     rsa_key = OpenSSL::PKey::RSA.new(config[:private_rsa_key])
 
     # Generate a new Symmetric Key pair
-    key_pair = SymmetricEncryption::Cipher.random_key_pair(cipher || 'aes-256-cbc', !iv_filename.nil?)
+    key_pair = SymmetricEncryption::Cipher.random_key_pair(cipher_name || 'aes-256-cbc', !iv_filename.nil?)
 
     # Save symmetric key after encrypting it with the private RSA key, backing up existing files if present
     File.rename(key_filename, "#{key_filename}.#{Time.now.to_i}") if File.exist?(key_filename)
@@ -207,15 +236,15 @@ module SymmetricEncryption
     config = YAML.load_file(filename || File.join(Rails.root, "config", "symmetric-encryption.yml"))[environment || Rails.env]
 
     # Default cipher
-    default_cipher = config['cipher'] || 'aes-256-cbc'
+    default_cipher = config['cipher_name'] || config['cipher'] || 'aes-256-cbc'
     cfg = {}
 
     # Hard coded symmetric_key? - Dev / Testing use only!
     if symmetric_key = (config['key'] || config['symmetric_key'])
       raise "SymmetricEncryption Cannot hard code Production encryption keys in #{filename}" if (environment || Rails.env) == 'production'
-      cfg[:key]     = symmetric_key
-      cfg[:iv]      = config['iv'] || config['symmetric_iv']
-      cfg[:cipher]  = default_cipher
+      cfg[:key]          = symmetric_key
+      cfg[:iv]           = config['iv'] || config['symmetric_iv']
+      cfg[:cipher_name]  = default_cipher
 
     elsif ciphers = config['ciphers']
       raise "Missing mandatory config parameter 'private_rsa_key'" unless cfg[:private_rsa_key] = config['private_rsa_key']
@@ -225,7 +254,7 @@ module SymmetricEncryption
         raise "Missing mandatory 'key_filename' for environment:#{environment} in #{filename}" unless key_filename
         iv_filename = cipher_cfg['iv_filename'] || cipher_cfg['symmetric_iv_filename']
         {
-          :cipher       => cipher_cfg['cipher'] || default_cipher,
+          :cipher_name  => cipher_cfg['cipher_name'] || cipher_cfg['cipher'] || default_cipher,
           :key_filename => key_filename,
           :iv_filename  => iv_filename,
           :encoding     => cipher_cfg['encoding'],
@@ -237,7 +266,7 @@ module SymmetricEncryption
       # Migrate old format config
       raise "Missing mandatory config parameter 'private_rsa_key'" unless cfg[:private_rsa_key] = config['private_rsa_key']
       cfg[:ciphers] = [ {
-          :cipher       => default_cipher,
+          :cipher_name  => default_cipher,
           :key_filename => config['symmetric_key_filename'],
           :iv_filename  => config['symmetric_iv_filename'],
         } ]
@@ -252,16 +281,17 @@ module SymmetricEncryption
   # Raises an Exception on failure
   #
   # Parameters:
-  #   cipher
-  #     Encryption cipher for the symmetric encryption key
-  #   private_key
+  #   private_rsa_key
   #     Key used to unlock file containing the actual symmetric key
-  #   key_filename
-  #     Name of file containing symmetric key encrypted using the public
-  #     key matching the supplied private_key
-  #   iv_filename
-  #     Optional. Name of file containing symmetric key initialization vector
-  #     encrypted using the public key matching the supplied private_key
+  #   cipher_conf Hash:
+  #     cipher_name
+  #       Encryption cipher name for the symmetric encryption key
+  #     key_filename
+  #       Name of file containing symmetric key encrypted using the public
+  #       key matching the supplied private_key
+  #     iv_filename
+  #       Optional. Name of file containing symmetric key initialization vector
+  #       encrypted using the public key matching the supplied private_key
   def self.cipher_from_encrypted_files(private_rsa_key, cipher_conf)
     # Load Encrypted Symmetric keys
     key_filename =  cipher_conf[:key_filename]
@@ -286,11 +316,11 @@ module SymmetricEncryption
     rsa = OpenSSL::PKey::RSA.new(private_rsa_key)
     iv = rsa.private_decrypt(encrypted_iv) if iv_filename
     Cipher.new(
-      :key      => rsa.private_decrypt(encrypted_key),
-      :iv       => iv,
-      :cipher   => cipher_conf[:cipher],
-      :encoding => cipher_conf[:encoding],
-      :version  => cipher_conf[:version]
+      :key         => rsa.private_decrypt(encrypted_key),
+      :iv          => iv,
+      :cipher_name => cipher_conf[:cipher_name],
+      :encoding    => cipher_conf[:encoding],
+      :version     => cipher_conf[:version]
     )
   end
 

data/lib/symmetric_encryption/version.rb

@@ -1,4 +1,4 @@
 # encoding: utf-8
 module SymmetricEncryption #:nodoc
-  VERSION = "1.1.1"
+  VERSION = "2.0.0"
 end

data/lib/symmetric_encryption/writer.rb

@@ -1,3 +1,5 @@
+require 'openssl'
+
 module SymmetricEncryption
   # Write to encrypted files and other IO streams
   #
@@ -24,12 +26,23 @@ module SymmetricEncryption
     #          Default: false
     #
     #     :random_key [true|false]
-    #          Generates a new random key and iv for every new file or stream
+    #          Generates a new random key for every new file or stream
     #          If true, it forces header to true. Version below then has no effect
-    #          The Random key and iv will be written to the file/stream in encrypted
+    #          The Random key will be written to the file/stream in encrypted
     #          form as part of the header
-    #          The key and iv are both encrypted using the global key
+    #          The key is encrypted using the global key
     #          Default: true
+    #          Recommended: true.
+    #            Setting to false will eventually expose the
+    #            encryption key since too much data will be encrypted using the
+    #            same encryption key
+    #
+    #     :random_iv [true|false]
+    #          Generates a new random iv for every new file or stream
+    #          If true, it forces header to true.
+    #          The Random iv will be written to the file/stream in encrypted
+    #          form as part of the header
+    #          Default: Value supplied above for :random_key
     #          Recommended: true. Setting to false will eventually expose the
     #            encryption key since too much data will be encrypted using the
     #            same encryption key
@@ -49,12 +62,17 @@ module SymmetricEncryption
     #
     #          When random_key is false, the version of the encryption key to use
     #          to encrypt the entire file
-    #          Default: Current primary key
+    #          Default: SymmetricEncryption.cipher
     #
     #     :mode
     #          See File.open for open modes
     #          Default: 'w'
     #
+    #     :cipher_name
+    #          The name of the cipher to use only if both :random_key and
+    #          :random_iv are true.
+    #          Default: SymmetricEncryption.cipher.cipher_name
+    #
     # Note: Compression occurs before encryption
     #
     #
@@ -97,22 +115,50 @@ module SymmetricEncryption
 
     # Encrypt data before writing to the supplied stream
     def initialize(ios,options={})
-      @ios       = ios
-      header     = options.fetch(:header, true)
+      @ios        = ios
+      header      = options.fetch(:header, true)
+      random_key  = options.fetch(:random_key, true)
+      random_iv   = options.fetch(:random_iv, random_key)
+      raise "When :random_key is true, :random_iv must also be true" if random_key && !random_iv
       # Compress is only used at this point for setting the flag in the header
-      random_key = options.fetch(:random_key, true)
-      compress   = options.fetch(:compress, false)
-      # Force header if compressed or using random iv, key pair
-      header     = true if compress || random_key
+      compress    = options.fetch(:compress, false)
+      version     = options[:version]
+      cipher_name = options[:cipher_name]
+      raise "Cannot supply a :cipher_name unless both :random_key and :random_iv are true" if cipher_name && !random_key && !random_iv
+
+      # Force header if compressed or using random iv, key
+      header = true if compress || random_key || random_iv
+
+      cipher = nil
+      if random_key
+        # Version of key used to encrypt the random key
+        version = SymmetricEncryption.cipher.version
+      else
+        # Use global key if a new random one is not being generated
+        cipher = SymmetricEncryption.cipher(version)
+        raise "Cipher with version:#{version} not found in any of the configured SymmetricEncryption ciphers" unless cipher
+        # Version of key used to encrypt the data
+        version = cipher.version
+      end
+
+      @stream_cipher = ::OpenSSL::Cipher.new(cipher_name || SymmetricEncryption.cipher.cipher_name)
+      @stream_cipher.encrypt
 
-      # Create random cipher or use global primary cipher
-      @cipher = random_key ? SymmetricEncryption::Cipher.random_cipher : SymmetricEncryption.cipher(options[:version])
-      raise "Cipher with version:#{options[:version]} not found in any of the configured SymmetricEncryption ciphers" unless @cipher
+      key = random_key ? @stream_cipher.random_key : cipher.send(:key)
+      iv = random_iv ? @stream_cipher.random_iv : cipher.send(:iv)
 
-      @stream_cipher = @cipher.send(:openssl_cipher, :encrypt)
+      @stream_cipher.key = key
+      @stream_cipher.iv = iv if iv
 
       # Write the Encryption header including the random iv, key, and cipher
-      @ios.write(@cipher.magic_header(compress, random_key, random_key, random_key)) if header
+      if header
+        @ios.write(Cipher.magic_header(
+            version,
+            compress,
+            random_iv  ? iv : nil,
+            random_key ? key : nil,
+            cipher_name))
+      end
     end
 
     # Close the IO Stream