symmetric-encryption 3.2 → 3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: acc34e0886fa7dcf660847dd29c02a34b102a815
-  data.tar.gz: 2e74557115bc5fc5da4f899271f756f34a6af987
+  metadata.gz: 37b9132a3f23db50841774bccd1d0ea48db0a325
+  data.tar.gz: 66808f69ba790855acac29dcd2ca59b59ec5a611
 SHA512:
-  metadata.gz: 9760706ef46ddd952e26b10fbea5007b51e8bfc5fedc85b7827fa4a3119850c089d1865d86b7ced4d8b5037117aa23b06eeb0c7f0841a56240823a28f09ac4c0
-  data.tar.gz: e2b5991b164831c50519c5dd0879f1f5d720909bbcb57ff6a4537219ba58268cfa3425bcc0b10515a0f23a1783c6ba67a201ae3a18c7002de125e1d5ab173705
+  metadata.gz: 33ba910830b6f113ccefe74d029e2ec5d68f3ea15234bae0234c7de335d9d9e29f13edbc248398f6d766e02277ee22535f8d274cae10b48bcc9b8f388de81af5
+  data.tar.gz: c0dbfec5a29239451d18cd4ec8eef68f891100267a1b670e4b9224861b3cf9321ae7f525fc08ca7927aca260c72ec6696da40cca57af243d343bf288b28c40be

data/LICENSE.txt

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2012 Clarity Services, Inc.
+   Copyright 2012, 2013, 2014 Reid Morrison
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

data/README.md

@@ -1,7 +1,7 @@
 symmetric-encryption
 ====================
 
-* http://github.com/ClarityServices/symmetric-encryption
+* http://github.com/reidmorrison/symmetric-encryption
 
 ## Introduction
 
@@ -163,18 +163,40 @@ class User < ActiveRecord::Base
   # Requires table users to have a column called encrypted_bank_account_number
   attr_encrypted :bank_account_number
 
-  # Requires table users to have a column called encrypted_social_security_number
+  # Requires users table to have a column called encrypted_social_security_number
+  #
+  # Note: Encrypting the same value twice will result in the _same_ encrypted value
+  #       when :random_iv => false, or is not specified
   attr_encrypted :social_security_number
 
+  # By specifying the type as :integer the value will be returned as an integer and
+  # can be set as an integer, even though it is stored in the database as an
+  # encrypted string
+  #
+  # Requires users table to have a column called encrypted_age of type string
+  attr_encrypted :age,         :type => :integer
+
   # Since string and long_string are not used in the where clause of any SQL
   # queries it is better to ensure that the encrypted value is always different
   # by encrypting every value with a random Initialization Vector.
+  #
+  # Note: Encrypting the same value twice will result in different encrypted
+  #       values when :random_iv => true
   attr_encrypted :string,      :random_iv => true
 
   # Long encrypted strings can also be compressed prior to encryption to save
   # disk space
   attr_encrypted :long_string, :random_iv => true, :compress => true
 
+  # By specifying the type as :json the value will be serialized to JSON
+  # before encryption and deserialized from JSON after decryption.
+  #
+  # It is sometimes useful to use compression on large fields, so we can enable
+  # compression before the string is encrypted
+  #
+  # Requires users table to have a column called encrypted_values of type string
+  attr_encrypted :values,      :type => :json, :compress => true
+
   validates :encrypted_bank_account_number, :symmetric_encryption => true
   validates :encrypted_social_security_number, :symmetric_encryption => true
 end
@@ -191,6 +213,19 @@ user.save!
 User.create(:bank_account_number => '12345')
 ```
 
+Several types are supported for ActiveRecord models when encrypting or decrypting data.
+Each type maps to the built-in Ruby types as follows:
+
+- :string    => String
+- :integer   => Integer
+- :float     => Float
+- :decimal   => BigDecimal
+- :datetime  => DateTime
+- :time      => Time
+- :date      => Date
+- :json      => Uses JSON serialization, useful for hashes and arrays
+- :yaml      => Uses YAML serialization, useful for hashes and arrays
+
 ### Mongoid Example
 
 To encrypt a field in a Mongoid document, just add ":encrypted => true" at the end
@@ -205,6 +240,13 @@ class User
   field :encrypted_bank_account_number,    :type => String,  :encrypted => true
   field :encrypted_social_security_number, :type => String,  :encrypted => true
   field :encrypted_life_history,           :type => String,  :encrypted => {:compress => true, :random_iv => true}
+
+  # Encrypted fields are _always_ stored in Mongo as a String
+  # To get the result back as an Integer, Symmetric Encryption can do the
+  # necessary conversions by specifying the internal type as an option
+  # to :encrypted
+  # #see SymmetricEncryption::COERCION_TYPES for full list of types
+  field :encrypted_age,                    :type => String, :encrypted => {:type => :integer}
 end
 
 # Create a new user document
@@ -217,6 +259,8 @@ user = User.where(:encrypted_bank_account_number => SymmetricEncryption.encrypt(
 puts user.bank_account_number
 ```
 
+Note: At this time Symmetric Encryption only supports Mongoid fields with a type of String
+
 ### Validation Example
 
 ```ruby
@@ -327,6 +371,13 @@ Encrypt a known value, such as a password:
 Note: Passwords must be encrypted in the environment in which they will be used.
   Since each environment should have its own symmetric encryption keys
 
+Note: To use the rake task 'symmetric_encryption:encrypt' the gem 'highline'
+  must first be installed by adding to bundler or installing directly:
+
+```ruby
+gem install 'highline'
+```
+
 Encrypt a file
 
     INFILE="Gemfile.lock" OUTFILE="Gemfile.lock.encrypted" rake symmetric_encryption:encrypt_file
@@ -614,9 +665,9 @@ production:
 Meta
 ----
 
-* Code: `git clone git://github.com/ClarityServices/symmetric-encryption.git`
-* Home: <https://github.com/ClarityServices/symmetric-encryption>
-* Issues: <http://github.com/ClarityServices/symmetric-encryption/issues>
+* Code: `git clone git://github.com/reidmorrison/symmetric-encryption.git`
+* Home: <https://github.com/reidmorrison/symmetric-encryption>
+* Issues: <http://github.com/reidmorrison/symmetric-encryption/issues>
 * Gems: <http://rubygems.org/gems/symmetric-encryption>
 
 This project uses [Semantic Versioning](http://semver.org/).
@@ -624,12 +675,17 @@ This project uses [Semantic Versioning](http://semver.org/).
 Authors
 -------
 
-Reid Morrison :: reidmo@gmail.com :: @reidmorrison
+[Reid Morrison](https://github.com/reidmorrison)
+
+Contributors
+------------
+
+[M. Scott Ford](https://github.com/mscottford)
 
 License
 -------
 
-Copyright 2012 Clarity Services, Inc.
+Copyright 2012, 2013, 2014 Reid Morrison
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -643,9 +699,9 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 
-Compliance
+Disclaimer
 ----------
 
-Although this library has assisted Clarity in meeting PCI Compliance it in no
-way guarantees that PCI Compliance will be met by anyone using this library
-for encryption purposes.
+Although this library has assisted in meeting PCI Compliance and has passed
+previous PCI audits, it in no way guarantees that PCI Compliance will be
+achieved by anyone using this library.

data/lib/symmetric_encryption.rb

@@ -1,4 +1,8 @@
+# Used for compression
 require 'zlib'
+# Used to coerce data types between string and their actual types
+require 'coercible'
+
 require 'symmetric_encryption/version'
 require 'symmetric_encryption/cipher'
 require 'symmetric_encryption/symmetric_encryption'
@@ -10,13 +14,7 @@ end
 if defined?(Rails)
   require 'symmetric_encryption/railtie'
 end
-# attr_encrypted and Encrypted validator
-if defined?(ActiveRecord::Base)
-  require 'symmetric_encryption/extensions/active_record/base'
-  require 'symmetric_encryption/railties/symmetric_encryption_validator'
-end
 
-# field encryption for Mongoid
-if defined?(Mongoid)
-  require 'symmetric_encryption/mongoid'
-end
+require 'symmetric_encryption/extensions/active_record/base' if defined?(ActiveRecord::Base)
+require 'symmetric_encryption/railties/symmetric_encryption_validator' if defined?(ActiveModel)
+require 'symmetric_encryption/mongoid' if defined?(Mongoid)

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

@@ -9,10 +9,6 @@ module ActiveRecord #:nodoc:
       # * Symbolic names of each method to create which has a corresponding
       #   method already defined in rails starting with: encrypted_
       # * 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.
@@ -29,6 +25,10 @@ module ActiveRecord #:nodoc:
       #       Default: false
       #       Highly Recommended where feasible: true
       #
+      #     :type [Symbol]
+      #       The type for this field, #see SymmetricEncryption::COERCION_TYPES
+      #       Default: :string
+      #
       #     :compress [true|false]
       #       Whether to compress str before encryption
       #       Should only be used for large strings since compression overhead and
@@ -41,20 +41,38 @@ module ActiveRecord #:nodoc:
         # 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)
+        options   = params.last.is_a?(Hash) ? params.pop.dup : {}
+        random_iv = options.delete(:random_iv) || false
+        compress  = options.delete(:compress) || false
+        type      = options.delete(:type) || :string
+
+        raise "Invalid type: #{type.inspect}. Valid types: #{SymmetricEncryption::COERCION_TYPES.inspect}" unless SymmetricEncryption::COERCION_TYPES.include?(type)
+
+        # For backward compatibility
+        if options.delete(:marshal) == true
+          warn("The :marshal option has been deprecated in favor of :type. For example: attr_encrypted name, :type => :yaml")
+          raise "Marshal is depreacted and cannot be used in conjunction with :type, just use :type. For #{params.inspect}" if type != :string
+          type = :yaml
+        end
+
+        options.each {|option| warn "Ignoring unknown option #{option.inspect} supplied to attr_encrypted with #{params.inspect}"}
+
+        if const_defined?(:EncryptedAttributes, _search_ancestors = false)
+          mod = const_get(:EncryptedAttributes)
+        else
+          mod = const_set(:EncryptedAttributes, Module.new)
+          include mod
+        end
 
         params.each do |attribute|
           # Generate unencrypted attribute with getter and setter
-          class_eval(<<-UNENCRYPTED, __FILE__, __LINE__ + 1)
+          mod.module_eval(<<-UNENCRYPTED, __FILE__, __LINE__ + 1)
             # Returns the decrypted value for the encrypted attribute
             # The decrypted value is cached and is only decrypted if the encrypted value has changed
             # If this method is not called, then the encrypted value is never decrypted
             def #{attribute}
               if @stored_encrypted_#{attribute} != self.encrypted_#{attribute}
-                @#{attribute} = ::SymmetricEncryption.decrypt(self.encrypted_#{attribute}).freeze
+                @#{attribute} = ::SymmetricEncryption.decrypt(self.encrypted_#{attribute},version=nil,:#{type}).freeze
                 @stored_encrypted_#{attribute} = self.encrypted_#{attribute}
               end
               @#{attribute}
@@ -63,7 +81,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 marshal},#{random_iv},#{compress})
+              self.encrypted_#{attribute} = @stored_encrypted_#{attribute} = ::SymmetricEncryption.encrypt(value,#{random_iv},#{compress},:#{type})
               @#{attribute} = value.freeze
             end
           UNENCRYPTED

data/lib/symmetric_encryption/mongoid.rb

@@ -17,8 +17,15 @@
 #
 #    field :name,                             :type => String
 #    field :encrypted_social_security_number, :type => String, :encrypted => true
-#    field :age,                              :type => Integer
+#    field :date_of_birth,                    :type => Date
 #    field :encrypted_life_history,           :type => String, :encrypted => {:compress => true, :random_iv => true}
+#
+#    # Encrypted fields are _always_ stored in Mongo as a String
+#    # To get the result back as an Integer, Symmetric Encryption can do the
+#    # necessary conversions by specifying the internal type as an option
+#    # to :encrypted
+#    # #see SymmetricEncryption::COERCION_TYPES for full list of types
+#    field :encrypted_age,                    :type => String, :encrypted => {:type => :integer, :random_iv => true}
 #  end
 #
 # The above document results in the following document in the Mongo collection 'persons':
@@ -67,9 +74,13 @@
 # @param [ Hash ] options The options to pass to the field.
 #
 # @option options [ Boolean | Hash ] :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.
+#   When :encrypted is a Hash it consists of:
+#     @option options [ Symbol ]  :type The type for this field, #see SymmetricEncryption::COERCION_TYPES
+#     @option options [ Boolean ] :random_iv  Whether the encrypted value should use a random IV every time the field is encrypted.
+#     @option options [ Boolean ] :compress   Whether to compress this encrypted field
+#     @option options [ Symbol ]  :decrypt_as Name of the getters and setters to generate to access the decrypted value of this field.
+#
+# Some of the other regular Mongoid options:
 #
 # @option options [ Class ]   :type The type of the field.
 # @option options [ String ]  :label The label for the field.
@@ -90,14 +101,25 @@ Mongoid::Fields.option :encrypted do |model, field, options|
 
     random_iv = options.delete(:random_iv) || false
     compress  = options.delete(:compress) || false
+    type      = options.delete(:type) || :string
+    raise "Invalid type: #{type.inspect}. Valid types: #{SymmetricEncryption::COERCION_TYPES.inspect}" unless SymmetricEncryption::COERCION_TYPES.include?(type)
+
+    options.each {|option| warn "Ignoring unknown option #{option.inspect} supplied to Mongoid :encrypted for #{model}##{field}"}
+
+    if model.const_defined?(:EncryptedAttributes, _search_ancestors = false)
+      mod = model.const_get(:EncryptedAttributes)
+    else
+      mod = model.const_set(:EncryptedAttributes, Module.new)
+      model.send(:include, mod)
+    end
 
     # Generate getter and setter methods
-    model.class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+    mod.module_eval(<<-EOS, __FILE__, __LINE__ + 1)
       # Set the un-encrypted field
       # Also updates the encrypted field with the encrypted value
       # Freeze the decrypted field value so that it is not modified directly
       def #{decrypted_field_name}=(value)
-        self.#{encrypted_field_name} = @stored_#{encrypted_field_name} = ::SymmetricEncryption.encrypt(value,#{random_iv},#{compress})
+        self.#{encrypted_field_name} = @stored_#{encrypted_field_name} = ::SymmetricEncryption.encrypt(value,#{random_iv},#{compress},:#{type})
         @#{decrypted_field_name} = value.freeze
       end
 
@@ -106,7 +128,7 @@ Mongoid::Fields.option :encrypted do |model, field, options|
       # If this method is not called, then the encrypted value is never decrypted
       def #{decrypted_field_name}
         if @stored_#{encrypted_field_name} != self.#{encrypted_field_name}
-          @#{decrypted_field_name} = ::SymmetricEncryption.decrypt(self.#{encrypted_field_name}).freeze
+          @#{decrypted_field_name} = ::SymmetricEncryption.decrypt(self.#{encrypted_field_name},version=nil,:#{type}).freeze
           @stored_#{encrypted_field_name} = self.#{encrypted_field_name}
         end
         @#{decrypted_field_name}

data/lib/symmetric_encryption/railties/symmetric_encryption.rake

@@ -8,7 +8,11 @@ namespace :symmetric_encryption do
 
   desc 'Encrypt a value, such as a password. Example: rake symmetric_encryption:encrypt'
   task :encrypt => :environment do
-    require 'highline'
+    begin
+      require 'highline'
+    rescue LoadError
+      raise "Please install gem highline before using the command line task to encrypt an entered string.\n   gem install \"highline\""
+    end
     password1 = nil
     password2 = 0
 

data/lib/symmetric_encryption/symmetric_encryption.rb

@@ -14,6 +14,20 @@ module SymmetricEncryption
   @@secondary_ciphers = []
   @@select_cipher = nil
 
+  # List of types supported when encrypting or decrypting data
+  #
+  # Each type maps to the built-in Ruby types as follows:
+  #   :string    => String
+  #   :integer   => Integer
+  #   :float     => Float
+  #   :decimal   => BigDecimal
+  #   :datetime  => DateTime
+  #   :time      => Time
+  #   :date      => Date
+  #   :json      => Uses JSON serialization, useful for hashes and arrays
+  #   :yaml      => Uses YAML serialization, useful for hashes and arrays
+  COERCION_TYPES = [:string, :integer, :float, :decimal, :datetime, :time, :date, :boolean, :json, :yaml]
+
   # Set the Primary Symmetric Cipher to be used
   #
   # Example: For testing purposes the following test cipher can be used:
@@ -58,8 +72,8 @@ module SymmetricEncryption
   end
 
   # AES Symmetric Decryption of supplied string
-  #  Returns decrypted string
-  #  Returns nil if the supplied str is nil
+  #  Returns decrypted value
+  #  Returns nil if the supplied value is nil
   #  Returns "" if it is a string and it is empty
   #
   #  Parameters
@@ -68,6 +82,13 @@ module SymmetricEncryption
   #    version
   #      Specify which cipher version to use if no header is present on the
   #      encrypted string
+  #    type [:string|:integer|:float|:decimal|:datetime|:time|:date|:boolean]
+  #      If value is set to something other than :string, then the coercible gem
+  #      will be use to coerce the unencrypted string value into the specified
+  #      type. This assumes that the value was stored using the same type.
+  #      Note: If type is set to something other than :string, it's expected
+  #        that the coercible gem is available in the path.
+  #      Default: :string
   #
   #  If the supplied string has an encryption header then the cipher matching
   #  the version number in the header will be used to decrypt the string
@@ -84,7 +105,7 @@ module SymmetricEncryption
   #       yet significant number of cases it is possible to decrypt data using
   #       the incorrect key. Clearly the data returned is garbage, but it still
   #       successfully returns a string of data
-  def self.decrypt(encrypted_and_encoded_string, version=nil)
+  def self.decrypt(encrypted_and_encoded_string, version=nil, type=:string)
     raise "Call SymmetricEncryption.load! or SymmetricEncryption.cipher= prior to encrypting or decrypting data" unless @@cipher
     return encrypted_and_encoded_string if encrypted_and_encoded_string.nil? || (encrypted_and_encoded_string == '')
 
@@ -109,7 +130,7 @@ module SymmetricEncryption
         decrypted.force_encoding(SymmetricEncryption::BINARY_ENCODING)
       end
     end
-    decrypted
+    coerce_from_string(decrypted, type)
   end
 
   # AES Symmetric Encryption of supplied string
@@ -118,7 +139,7 @@ module SymmetricEncryption
   #  Returns "" if it is a string and it is empty
   #
   # Parameters
-  #   str [String]
+  #   value [Object]
   #     String to be encrypted. If str is not a string, #to_s will be called on it
   #     to convert it to a string
   #
@@ -145,11 +166,20 @@ module SymmetricEncryption
   #     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)
+  #
+  #   type [:string|:integer|:float|:decimal|:datetime|:time|:date|:boolean]
+  #     Expected data type of the value to encrypt
+  #     Uses the coercible gem to coerce non-string values into string values.
+  #     When type is set to :string (the default), uses #to_s to convert
+  #     non-string values to string values.
+  #     Note: If type is set to something other than :string, it's expected that
+  #       the coercible gem is available in the path.
+  #     Default: :string
+  def self.encrypt(str, random_iv=false, compress=false, type=:string)
     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, random_iv, compress)
+    @@cipher.encrypt(coerce_to_string(str, type), random_iv, compress)
   end
 
   # Invokes decrypt
@@ -425,6 +455,63 @@ module SymmetricEncryption
     Cipher.new(config)
   end
 
+  # Uses coercible gem to coerce values from strings into the target type
+  # Note: if the type is :string, then the value is returned as is, and the
+  #   coercible gem is not used at all.
+  def self.coerce_from_string(value, type)
+    return if value.nil?
+    case type
+    when :string
+      value
+    when :json
+      JSON.load(value)
+    when :yaml
+      YAML.load(value)
+    else
+      coercer = Coercible::Coercer.new
+      coercion_method = "to_#{type}".to_sym
+      coercer[String].send(coercion_method, value)
+    end
+  end
+
+  # Uses coercible gem to coerce values to strings from the specified type
+  # Note: if the type is :string, and value is not nil, then #to_s is called
+  #   on the value and the coercible gem is not used at all.
+  def self.coerce_to_string(value, type)
+    return if value.nil?
+
+    case type
+    when :string
+      value.to_s
+    when :json
+      value.to_json
+    when :yaml
+      value.to_yaml
+    else
+      coercer = Coercible::Coercer.new
+      coercer[coercion_type(type, value)].to_string(value)
+    end
+  end
+
+  # Returns the correct coercion type to use for the specified symbol and value
+  def self.coercion_type(symbol, value)
+    if symbol == :boolean
+      value.class
+    else
+      COERCION_TYPE_MAP[symbol]
+    end
+  end
+
+  COERCION_TYPE_MAP = {
+    :string => String,
+    :integer => Integer,
+    :float => Float,
+    :decimal => BigDecimal,
+    :datetime => DateTime,
+    :time => Time,
+    :date => Date
+  }
+
   # With Ruby 1.9 strings have encodings
   if defined?(Encoding)
     BINARY_ENCODING = Encoding.find("binary")