attribute_queryable_encrypted 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+pkg/*
+*.gem
+.bundle
+spec/db/*.sqlite3

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in attribute_queryable_encrypted.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,29 @@
+PATH
+  remote: .
+  specs:
+    attribute_queryable_encrypted (0.0.1)
+      active_support (>= 3.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    active_support (3.0.0)
+      activesupport (= 3.0.0)
+    activesupport (3.0.0)
+    diff-lcs (1.1.3)
+    rspec (2.7.0)
+      rspec-core (~> 2.7.0)
+      rspec-expectations (~> 2.7.0)
+      rspec-mocks (~> 2.7.0)
+    rspec-core (2.7.1)
+    rspec-expectations (2.7.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.7.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  active_support (>= 3.0)
+  attribute_queryable_encrypted!
+  rspec

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/attribute_queryable_encrypted.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "attribute_queryable_encrypted/version"
+
+Gem::Specification.new do |s|
+  s.name        = "attribute_queryable_encrypted"
+  s.version     = AttributeQueryableEncrypted::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Scott Burton"]
+  s.email       = ["scott@chaione.com"]
+  s.homepage    = "https://github.com/chaione/attribute_queryable_encrypted"
+  s.summary     = %q{Makes querying encrypted & salted attributes mildly less horrible}
+  s.description = %q{Makes querying encrypted & salted attributes mildly less horrible}
+
+  s.rubyforge_project = "attribute_queryable_encrypted"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  
+  s.add_dependency "active_support", ">= 3.0"
+  s.add_development_dependency "rspec"
+end

data/lib/attribute_queryable_encrypted.rb

@@ -0,0 +1,10 @@
+require 'active_support/concern'
+require 'active_support/core_ext/array/extract_options'
+require 'active_support/core_ext/class/attribute'
+require 'digest'
+require 'attribute_queryable_encrypted/core_ext/lower_higher'
+require 'attribute_queryable_encrypted/core_ext/prefix'
+require 'attribute_queryable_encrypted/core_ext/stretch_digest'
+require 'attribute_queryable_encrypted/prefix_attributes'
+require 'attribute_queryable_encrypted/railtie' if defined? Rails
+require 'attribute_queryable_encrypted/adapters/active_record' if defined? ActiveRecord

data/lib/attribute_queryable_encrypted/adapters/active_record.rb

@@ -0,0 +1,46 @@
+module AttributeQueryableEncrypted
+  module Adapters
+    module ActiveRecord
+      extend ActiveSupport::Concern
+
+      include AttributeQueryableEncrypted::PrefixAttributes
+      
+      included do
+        attrbute_queryable_encrypted_default_options[:encode] = true
+      end
+      
+      module ClassMethods
+        def attribute_queryable_encrypted *args
+          define_attribute_methods rescue nil
+          super *args
+          
+          args.reject { |arg| arg.is_a?(Hash) }.each do |attribute|
+            options = queryable_encrypted_attributes[attribute]
+            
+            find_all_by_method = proc do |prefix_value|
+              send("find_all_by_#{[options[:prefix], attribute, options[:suffix]].join('_')}", prefix_encrypt(prefix_value, options))
+            end
+
+            find_by_method = proc do |original_value| 
+              send("find_all_by_#{[options[:prefix], attribute].join('_')}", original_value.prefix(options[:length])).detect do |result|
+                result[attribute] === original_value
+              end
+            end
+            
+            singleton = class << self
+              self
+            end
+            
+            alias_method "original_find_by_#{attribute}", "find_by_#{attribute}" if respond_to?(attribute)
+            
+            singleton.send(:define_method, "find_all_by_#{[options[:prefix], attribute].join('_')}", find_all_by_method)            
+            singleton.send(:define_method, "find_by_#{attribute}", find_by_method)
+
+          end
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send(:include, AttributeQueryableEncrypted::Adapters::ActiveRecord)

data/lib/attribute_queryable_encrypted/core_ext/lower_higher.rb

@@ -0,0 +1,17 @@
+module AttributeQueryableEncrypted
+  module CoreExt
+    module LowerHigher
+      # Returns the lower of self or n
+      def lower(n)
+        self < n ? self : n
+      end
+  
+      # Returns the higher of self or n
+      def higher(n)
+        self > n ? self : n
+      end
+    end
+  end
+end
+
+Numeric.send(:include, AttributeQueryableEncrypted::CoreExt::LowerHigher)

data/lib/attribute_queryable_encrypted/core_ext/prefix.rb

@@ -0,0 +1,24 @@
+module AttributeQueryableEncrypted
+  module CoreExt
+    module Prefix
+      # Returns an integer of the available length provided
+      # a fixed or percentage-based requested length, or self's
+      # length, whichever is lowest.
+      # 
+      # Examples
+      # "This is a string".prefix_length #=> 8
+      # "This is a string".prefix_length(1000) => 16
+      # "This is a string".prefix_length("75%") => 12
+      # 
+      def prefix_length(requested_length)
+        requested_length.is_a?(Numeric) ? length.lower(requested_length) : (length/(100/requested_length.match(/^([0-9.]+)%$/)[0].to_f)).ceil
+      end
+
+      def prefix(requested_length)
+        self[0, prefix_length(requested_length)]
+      end
+    end
+  end
+end
+
+String.send(:include, AttributeQueryableEncrypted::CoreExt::Prefix)

data/lib/attribute_queryable_encrypted/core_ext/stretch_digest.rb

@@ -0,0 +1,19 @@
+module AttributeQueryableEncrypted
+  module CoreExt
+    module StretchDigest
+      def stretch_digest(options={})
+        options[:digest] ||= Digest::SHA2
+        options[:stretches] ||= 1
+        
+        digest = options[:digest].new
+        options[:stretches].times do
+          string = options[:key] ? self + options[:key] : self
+          digest.update(string)
+        end
+        digest.to_s
+      end
+    end
+  end
+end
+
+String.send(:include, AttributeQueryableEncrypted::CoreExt::StretchDigest)

data/lib/attribute_queryable_encrypted/prefix_attributes.rb

@@ -0,0 +1,81 @@
+module AttributeQueryableEncrypted
+  module PrefixAttributes
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :queryable_encrypted_attributes, :attrbute_queryable_encrypted_default_options
+      self.queryable_encrypted_attributes = {}
+      self.attrbute_queryable_encrypted_default_options = {
+        :length     => "50%",
+        :prefix     => "prefix",
+        :suffix     => "digest",
+        :encode     => false,
+        :stretches  => 3
+      }
+    end
+
+    module ClassMethods
+      
+      # Assigns a digest-hashed value to an attribute writer using a portion of the 
+      # value assigned to each attribute's normal writer. The digest-hashed prefix
+      # can then be used to identify other objects with the same prefix without
+      # revealing the underlying value.
+      # 
+      # Example:
+      # --------
+      #   class HiddenValue                                                              
+      #     include AttributeQueryableEncrypted::PrefixAttributes                        
+      #     attr_writer :data                                                            
+      #     attr_accessor :prefix_data_digest                                            
+      #     attribute_queryable_encrypted :data                                          
+      #   end                                                                            
+      #                                                                                  
+      #   hider = HiddenValue.new                                                        
+      #                                                                                  
+      #   hider.data = "This is a string"                                                
+      #   hider.prefix_data_digest                                                       
+      #     # => "a37010c994067764d86540bf479d93b4d0c3bb3955de7b61f951caf2fd0301b0"      
+      # 
+      # This technique is valuable when the queryable encrypted attribute is not 
+      # persisted, or is persisted in a non-deterministic way (i.e. a salted, encrypted 
+      # database column)
+      # 
+      # 
+      # Options:
+      # --------
+      # :length - an integer value length, or percentage expressed as a string ("72%")
+      # :prefix - prefix name for the storage accessor. Default is "prefix"
+      # :suffix - suffix name for the storage accessor. Defuault is "suffix"
+      # :encode - Base64 encode the digest hash, suitable for database persistence. Default is false.
+      # 
+      def attribute_queryable_encrypted *attributes
+        
+        options = attrbute_queryable_encrypted_default_options.merge(attributes.extract_options!)
+        
+        attributes.each do |attribute|
+          queryable_encrypted_attributes[attribute] = options
+          class_eval do
+            alias_method "unprefixed_#{attribute}=".to_sym, "#{attribute}=".to_sym
+
+            define_method "#{attribute}=", do |*args, &blk|
+              send("#{[options[:prefix], attribute, options[:suffix]].join('_')}=".to_sym, prefix_encrypt(args[0], options))
+              send("unprefixed_#{attribute}=".to_sym, *args, &blk)
+            end
+          end
+        end
+      end
+      
+      def prefix_encrypt(value, options)
+        prefix_encrypted_value = value.prefix(options[:length]).stretch_digest(options)
+        prefix_encrypted_value = [prefix_encrypted_value].pack("m*") if options[:encode]
+        prefix_encrypted_value
+      end
+    end
+    
+    module InstanceMethods
+      def prefix_encrypt(value, options)
+        self.class.prefix_encrypt(value, options)
+      end
+    end
+  end
+end

data/lib/attribute_queryable_encrypted/version.rb

@@ -0,0 +1,3 @@
+module AttributeQueryableEncrypted
+  VERSION = "0.0.1"
+end

data/readme.md

@@ -0,0 +1,72 @@
+AttributeQueryableEncrypted
+===========================
+Assigns a digest-hashed value to an attribute writer using a portion of the value assigned to each attribute's normal writer. The digest-hashed prefix can then be used to identify other objects with the same prefix without revealing the underlying value.
+
+AttributeQueryableEncrypted was inspried by shuber's excellent [attr_encrypted](https://github.com/shuber/attr_encrypted) gem, and aims for compatibility. It attempts to addresses a shortcoming of encryption, where encrypted columns are queryable when unsalted, but attackable using a precomputed "rainbow table".
+
+Selecting multiple candidates with matching prefix digests and subsequently decrypting the full salted/encrypted data field to find a exact match will reduce the need for a full table scan. You should use attr_encrypted, or your own crypto logic, to handle encrypting and decrypting the appropriate full data field.
+
+Example:
+--------
+    class HiddenValue                                                              
+      include AttributeQueryableEncrypted::PrefixAttributes                                                        
+      attr_accessor :prefix_data_digest
+      attribute_queryable_encrypted :data
+      
+      def data=(something)
+        ...something fancy that obscures the data...
+      end
+    end                                                                            
+                                                                                 
+    hider = HiddenValue.new                                                        
+                                                                                 
+    hider.data = "This is a string"                                                
+    hider.prefix_data_digest                                                       
+      # => "a37010c994067764d86540bf479d93b4d0c3bb3955de7b61f951caf2fd0301b0"      
+
+
+ActiveRecord:
+-------------
+ActiveRecord users gain a query method for their prefix digest column:
+
+      HiddenValue.find_all_by_prefix_data("This is ")
+      # => [#<HiddenValue id: 1, encrypted_data: "MWE2ODg0ZTVmNTA2M2I3MTZmMWQxZGI3NzA0MjgyMzRj...", prefix_data_digest: "MTgyODBlMWFkNGZiMjAyZTc5Y2FiYTcxODZhYTg1OWM3OGNhOWI...">, #<HiddenValue id: 2, encrypted_data: "WQxZGI3NzANTA2M2I3MTZmMj0MjgyMzRMWE2ODg0ZTVm...", prefix_data_digest: "MTgyODBlMWFkNGZiMjAyZTc5Y2FiYTcxODZhYTg1OWM3OGNhOWI...">]
+
+The returned records - a subset of the full table - can then be iterated over to find an exact match.
+
+A convenience method is provided to do this for you - note that it requires an attribute getter method (but not necessarily a database column) that provides a cleartext match for your query argument:
+
+      HiddenValue.find_by_prefix_data("This is a string")
+      # => #<HiddenValue id: 1, encrypted_data: "MWE2ODg0ZTVmNTA2M2I3MTZmMWQxZGI3NzA0MjgyMzRj...", prefix_data_digest: "MTgyODBlMWFkNGZiMjAyZTc5Y2FiYTcxODZhYTg1OWM3OGNhOWI...">
+
+You'll need to create an appropriately-named prefix digest column on your own.
+
+
+Options:
+--------
+* :length     - an integer value length, or percentage expressed as a string ("72%"). Default is "50%".
+* :prefix     - prefix name for the storage accessor. Default is "prefix"
+* :suffix     - suffix name for the storage accessor. Defuault is "suffix"
+* :encode     - Base64 encode the digest hash, suitable for database persistence. Default is false.
+* :stretches  - an integer number of iterations through the digest algorithm. More will reduce the ease of a precomputed attack. Default is 3.
+* :key        - an optional key to salt the digest algorithm. Default is nil.
+
+If you choose to use :stretches and/or :key, you should keep their values secret.
+
+Requirements:
+-------------
+* ActiveSupport >= 3.0
+* ActiveRecord >= 3.0 for ActiveRecord usage
+
+Warnings
+--------
+* This technique is not without shortcomings, notably that the prefix digest is subject to a precomputed attack. 
+* You should consider using secret values for :stretches and :key, and setting the :length option to a level that obscures an appropriate amount of your data without potentially giving away too much.
+* Increasing :stretches incurs a small performance penalty.
+* Decreasing :length can return more records in the initial matched set, potentially decreasing performance.
+
+Copyright
+---------
+(The MIT License)
+
+&copy; 2011 (Scott Burton, ChaiOne)

data/spec/active_record_adapter_spec.rb

@@ -0,0 +1,31 @@
+require 'active_record'
+require 'logger'
+require 'spec_helper'
+
+ActiveRecord::Base.establish_connection(:adapter => "sqlite3", 
+                                        :database => File.dirname(__FILE__) + "/db/attribute_queryable_encrypted.sqlite3")
+
+ActiveRecord::Base.logger = Logger.new(STDOUT)
+ActiveRecord::Base.logger.level = 3
+
+load File.dirname(__FILE__) + '/db/schema.rb'
+
+class TestModel < ActiveRecord::Base
+  attribute_queryable_encrypted :data, :length => 9
+end
+
+describe TestModel do
+  before(:all) do
+    @match1, @match2, @not_match = ["This is a string", "This is another string", "This string doesn't match"].map {|data| TestModel.create(:data => data)}
+  end
+  
+  describe "class query methods" do
+    it "finds the model instances with the appropriate prefix data" do
+      TestModel.find_all_by_prefix_data("This is a").should eql([@match1, @match2])
+    end
+    
+    it "finds the first exact match for the full original value" do
+      TestModel.find_by_data("This is another string").should eql @match2
+    end
+  end
+end

data/spec/attribute_queryable_encrypted_spec.rb

@@ -0,0 +1,46 @@
+require 'spec_helper'
+
+class TestModel
+  attr_accessor :default_length_data, :prefix_default_length_data_digest
+  attr_accessor :fixed_length_data, :prefix_fixed_length_data_digest
+  attr_accessor :percentage_length_data, :prefix_percentage_length_data_digest
+  include AttributeQueryableEncrypted::PrefixAttributes
+  attrbute_queryable_encrypted_default_options[:encode] = false
+end
+
+describe TestModel do
+  let(:input_string) {"It's a wicked string"}
+  context "without a :length" do
+    before(:all) do
+      TestModel.attribute_queryable_encrypted :default_length_data
+    end
+    before(:each) do
+      subject.default_length_data = input_string
+    end
+
+    its(:prefix_default_length_data_digest) {should eql "bc1b6f5cd503fad53c32b002176ca65f0c7409194ecb987825d6875ce1392aa1"}
+    its(:default_length_data) {should eql input_string}
+  end
+  
+  context "with a :length" do
+    context "as an integer" do
+      before(:all) do
+        TestModel.attribute_queryable_encrypted :fixed_length_data, :length => 14
+      end
+      before(:each) do
+        subject.fixed_length_data = input_string
+      end
+
+      its(:prefix_fixed_length_data_digest) {should eql "9c0dcb0f5d3429f9ac6c8d7bd1e5b056fb326f677806dbd8d813d046e7f3e764"}
+    end
+    
+    context "as a string percentage" do
+      before(:each) do
+        TestModel.attribute_queryable_encrypted :percentage_length_data, :length => "75%"
+        subject.percentage_length_data = input_string
+      end
+
+      its(:prefix_percentage_length_data_digest) {should eql "0594e426cced44e4ea358b0dbc10f71ba622661a43a0f3b460a2437e85b43ddc"}
+    end
+  end
+end

data/spec/db/schema.rb

@@ -0,0 +1,8 @@
+ActiveRecord::Schema.define do
+  self.verbose = false
+
+  create_table :test_models, :force => true do |t|
+    t.string :data
+    t.string :prefix_data_digest
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+$: << ".." << "../lib"
+Dir[File.expand_path(File.join(__FILE__, "..", "..", "lib", "attribute_queryable_encrypted.rb"))].each {|file| require file }
+require 'rspec'

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification 
+name: attribute_queryable_encrypted
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Scott Burton
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-11-16 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: active_support
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        version: "3.0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: Makes querying encrypted & salted attributes mildly less horrible
+email: 
+- scott@chaione.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- Rakefile
+- attribute_queryable_encrypted.gemspec
+- lib/attribute_queryable_encrypted.rb
+- lib/attribute_queryable_encrypted/adapters/active_record.rb
+- lib/attribute_queryable_encrypted/core_ext/lower_higher.rb
+- lib/attribute_queryable_encrypted/core_ext/prefix.rb
+- lib/attribute_queryable_encrypted/core_ext/stretch_digest.rb
+- lib/attribute_queryable_encrypted/prefix_attributes.rb
+- lib/attribute_queryable_encrypted/railtie.rb
+- lib/attribute_queryable_encrypted/version.rb
+- readme.md
+- spec/active_record_adapter_spec.rb
+- spec/attribute_queryable_encrypted_spec.rb
+- spec/db/schema.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: https://github.com/chaione/attribute_queryable_encrypted
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: attribute_queryable_encrypted
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Makes querying encrypted & salted attributes mildly less horrible
+test_files: 
+- spec/active_record_adapter_spec.rb
+- spec/attribute_queryable_encrypted_spec.rb
+- spec/db/schema.rb
+- spec/spec_helper.rb