obfuscate_id 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 Nathan Amick
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,77 @@
+# ObfuscateId
+
+ObfuscateId is a simple Ruby on Rails plugin that hides your seqential Active Record ids.  Although having nothing to do with security, it can be used to make database record id information non-obvious.
+
+For new websites, you may not want to give away information about how many people are signed up.  Every website has a third user, but that third user doesn't have to know he is the third user.
+
+ObfuscateId turns a URL like this:
+
+    http://example.com/users/3
+
+into something like:
+
+    http://example.com/users/2356513904
+    
+ObfuscateId mixes up the ids in a simple, reversable hashing algorithm so that it can then automatically revert the hashed number back to 3 for record lookup without having to store a hash or tag in the database.  No migrations needed.
+
+If you have the opposite problem, and your site is scaling well, you might not want to leak that you are getting 50 new posts a minute.
+
+ObfuscateId turns your sequential Active Record ids into non-sequential, random looking, numeric ids.
+
+    # post 7000
+    http://example.com/posts/5270192353
+    # post 7001
+    http://example.com/posts/7107163820
+    # post 7002
+    http://example.com/posts/3296163828
+
+## Features
+
+* Extreemly simple. A single line of code in the model turns it on.
+* Transforms normal seqential ids into random-looking ten digit numerical strings.
+* Gently masks resource ids while retaining a cleaner look than using an encrypted hash.
+* No migrations or database changes are needed.  The record is still stored in the database with its original id.
+* Fast, no heavy calculation.
+
+
+## Installation
+
+Add the gem to your Gemfile.
+
+    gem "obfuscate_id"
+
+Run bundler.
+
+    bundle install
+
+Then, in your model, add a single line.  
+
+    class Post < ActiveRecord::Base
+      obfuscate_id
+    end
+
+## Customization
+
+If you want your obfuscated ids to be different than some other website using the same plugin, you can throw a random number (spin) at obfuscate_id to make it hash out unique ids for your app.
+
+    class Post < ActiveRecord::Base
+      obfuscate_id :spin => 89238723
+    end
+
+This is also useful for making different models in the same app have different obfuscated ids.
+
+## How it works
+
+ObfuscateId pairs each number, from 0 to 9999999999, with one and only one number in that same range.  That other number is paired back to the first.  This is an example of a minimal perfect hash function.   Within a set of ten billion numbers, it simply maps every number to a different 10 digit number, and back again.
+
+ObfuscateId switches the plain record id to the obfuscated id in the models `to_param` method.
+
+It then augments Active Record's `find` method on models that have have been initiated with the `obfuscate_id` method to quickly reverse this obfuscated id back to the plain id before building the database query. This means no migrations or changes to the database.
+
+## Limitations
+
+* This is not security.  ObfuscateId was created to lightly mask record id numbers for the casual user.  If you need to really secure your database ids (hint, you probably don't), you need to use real encryption like AES.
+* Works for up to ten billion database records.  ObfuscateId simply maps every integer below ten billion to some other number below ten billion.
+* To properly generate obfuscated urls, make sure you trigger the model's `to_param` method by passing in the whole object rather than just the id; do this: `post_path(@post)` not this: `post_path(@post.id)`.
+* Rails uses the real id rather than `to_param` in some places.  A simple view-source on a form will often show the real id. This can be avoided by taking certain precautions. 
+

data/Rakefile

@@ -0,0 +1,27 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ObfuscateId'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+

data/lib/obfuscate_id.rb

@@ -0,0 +1,53 @@
+module ObfuscateId
+
+  def obfuscate_id(options = {})
+    require 'obfuscate_id/scatter_swap'
+    extend ClassMethods 
+    include InstanceMethods
+    cattr_accessor :obfuscate_id_spin
+    self.obfuscate_id_spin = (options[:spin] || obfuscate_id_default_spin)
+  end
+
+  def self.hide(id)
+    ScatterSwap.hash(id)
+  end
+
+  def self.show(id)
+    ScatterSwap.reverse_hash(id)
+  end
+
+
+  module ClassMethods
+    def find(*args)
+      if has_obfuscated_id?
+        args[0] = ObfuscateId.show(args[0])
+      end
+      super(*args)
+    end
+
+    def has_obfuscated_id?
+      true
+    end
+
+    # Generate a default spin from the Model name
+    # This makes it easy to drop obfuscate_id onto any model
+    # and produce different obfuscated ids for different models
+    def obfuscate_id_default_spin
+      alphabet = Array("a".."z") 
+      number = name.split("").collect do |char|
+        alphabet.index(char)
+      end
+      number.join.to_i
+    end
+
+  end
+
+  module InstanceMethods
+    def to_param
+      ObfuscateId.hide(self.id)
+    end
+
+  end
+end
+
+ActiveRecord::Base.extend ObfuscateId

data/lib/obfuscate_id/run_scatter_swap.rb

@@ -0,0 +1,93 @@
+require './scatter_swap.rb'
+
+# This file isn't really part of the library, its pretty much spike code.. 
+# 
+# While developing this, I used this file to visualize what was going on with the numbers
+#
+# You can uncomment various methods at the bottom and then run it like this:
+#
+# watch -n1 ruby run_scatter_swap.rb
+# 
+# tweak the code a bit and see instant visual changes in the generated numbers
+
+def visualize_scatter_and_unscatter
+  # change this number to experiment with different values
+  rotations = 99
+
+  original = ScatterSwap.arrayify(123456789)
+  scattered = []
+  unscattered = []
+  puts original.join
+  puts "rotate!(#{rotations})"
+  10.times do
+    puts original.rotate!(rotations).join + "->" + scattered.push(original.pop).join
+  end
+  puts "scattered"
+  puts scattered.join
+  10.times do
+    puts unscattered.push(scattered.pop).join + "->" + unscattered.rotate!(rotations * -1).join
+  end
+
+  puts unscattered.join
+end
+
+
+def visualize_swapper_map
+  puts "swapper map"
+  10.times do |index|
+    key = 1
+    puts ScatterSwap.swapper_map(index).join.to_s
+  end
+end
+
+def visualize_hash
+  puts "hash"
+  40.times do |integer|
+    output = "|"
+    3.times do |index|
+      output += " #{(integer + (123456789 * index)).to_s.rjust(5, ' ')}"
+      output += " => #{hashed = ScatterSwap.hash(integer + (123456789 * index) ) }"
+      output += " => #{ScatterSwap.reverse_hash(hashed) } |"
+    end
+    puts output
+  end
+end
+
+
+def visualize_scatter
+  puts "original      scattered     unscattered"
+  20.times do |integer|
+    output = ""
+    2.times do |index|
+      original = ScatterSwap.arrayify(integer + (123456789 * index))
+      scattered = ScatterSwap.scatter(original.clone)
+      unscattered = ScatterSwap.unscatter(scattered.clone)
+      output += "#{original.join}" 
+      output += " => #{scattered.join}"
+      output += " => #{unscattered.join}    |    "
+    end
+    puts output
+  end
+end
+
+
+# find hash for lots of spins
+def visualize_spin
+  2000.times do |original|
+    hashed_values = []
+    9000000000.times do |spin|
+      hashed =  ScatterSwap.hash(original, spin)
+      if hashed_values.include? hashed
+        puts "collision: #{original} - #{spin} - #{hashed}"
+        break
+      end
+      hashed_values.push hashed
+    end
+  end
+end
+
+#visualize_spin
+#visualize_hash
+#visualize_scatter_and_unscatter
+#visualize_scatter
+#visualize_swapper_map

data/lib/obfuscate_id/scatter_swap.rb

@@ -0,0 +1,138 @@
+class ScatterSwap
+  # This is the hashing function behind ObfuscateId.
+  # https://github.com/namick/obfuscate_id
+  #
+  # Designing a hash function is a bit of a black art and
+  # being that I don't have math background, I must resort
+  # to this simplistic swaping and scattering of array elements.
+  #
+  # After writing this and reading/learning some elemental hashing techniques,
+  # I realize this library is what is known as a Minimal perfect hash function:
+  # http://en.wikipedia.org/wiki/Perfect_hash_function#Minimal_perfect_hash_function
+  #
+  # I welcome all improvements :-)
+  #
+  # If you have some comments or suggestions, please contact me on github
+  # https://github.com/namick
+  #
+  # - nathan amick
+  # 
+  #
+  # This library is built for integers that can be expressed with 10 digits:
+  # It zero pads smaller numbers... so the number one is expressed with:
+  # 0000000001
+  # The biggest number it can deal with is:
+  # 9999999999
+  #
+  # Since we are working with a limited sequential set of input integers, 10 billion,
+  # this algorithm will suffice for simple id obfuscation for many web apps.
+  # The largest value that Ruby on Rails default id, Mysql INT type, is just over 2 billion (2147483647)
+  # which is the same as 2 to the power of 31 minus 1, but considerably less than 10 billion.
+  #
+  # ScatterSwap is an integer hash function designed to have:
+  # - zero collisions ( http://en.wikipedia.org/wiki/Perfect_hash_function )
+  # - achieve avalanche ( http://en.wikipedia.org/wiki/Avalanche_effect )
+  # - reversable
+  #
+  # We do that by combining two distinct strategies.
+  #
+  # 1. Scattering - whereby we take the whole number, slice it up into 10 digits
+  # and rearange their places, yet retaining the same 10 digits.  This allows
+  # us to preserve the sum of all the digits, regardless of order.  This sum acts
+  # as a key to reverse this scattering effect.
+  # 
+  # 2. Swapping - when dealing with many sequential numbers that we don't want
+  # to look similar, scattering wont do us much good because so many of the
+  # digits are the same; it deoesn't help to scatter 9 zeros around, so we need
+  # to swap out each of those zeros for something else.. something different
+  # for each place in the 10 digit array; for this, we need a map so that we
+  # can reverse it.
+
+  # Convience class method pointing to the instance method
+  def self.hash(plain_integer, spin = 0)
+    new(plain_integer, spin).hash
+  end
+
+  # Convience class method pointing to the instance method
+  def self.reverse_hash(hashed_integer, spin = 0)
+    new(hashed_integer, spin).reverse_hash
+  end
+
+  def initialize(original_integer, spin = 0)
+    @original_integer = original_integer
+    @spin = spin
+    zero_pad  = original_integer.to_s.rjust(10, '0')
+    @working_array = zero_pad.split("").collect {|d| d.to_i}
+  end
+
+  attr_accessor :working_array
+
+  # obfuscates an integer up to 10 digits in length
+  def hash
+    swap
+    scatter
+    completed_string
+  end
+
+  # de-obfuscates an integer
+  def reverse_hash
+    unscatter
+    unswap
+    completed_string
+  end
+
+  def completed_string
+    @working_array.join
+  end
+
+  # We want a unique map for each place in the original number
+  def swapper_map(index)
+    array = (0..9).to_a
+    10.times.collect.with_index do |i|
+      array.rotate!(index + i ^ spin).pop
+    end
+  end
+
+  # Using a unique map for each of the ten places,
+  # we swap out one number for another
+  def swap
+    @working_array = @working_array.collect.with_index do |digit, index|
+      swapper_map(index)[digit]
+    end
+  end
+
+  # Reverse swap
+  def unswap
+    @working_array = @working_array.collect.with_index do |digit, index|
+      swapper_map(index).rindex(digit)
+    end
+  end
+
+  # Rearrange the order of each digit in a reversable way by using the 
+  # sum of the digits (which doesn't change regardless of order)
+  # as a key to record how they were scattered
+  def scatter
+    sum_of_digits = @working_array.inject(:+).to_i
+    @working_array = 10.times.collect do 
+      @working_array.rotate!(spin ^ sum_of_digits).pop
+    end
+  end
+
+  # Reverse the scatter
+  def unscatter
+    scattered_array = @working_array
+    sum_of_digits = scattered_array.inject(:+).to_i
+    @working_array = []
+    @working_array.tap do |unscatter| 
+      10.times do
+        unscatter.push scattered_array.pop
+        unscatter.rotate! (sum_of_digits ^ spin) * -1
+      end
+    end
+  end
+
+  # Add some spice so that different apps can have differently mapped hashes
+  def spin
+    @spin || 0
+  end
+end

data/lib/obfuscate_id/version.rb

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

data/lib/tasks/obfuscate_id_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :obfuscate_id do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: obfuscate_id
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Nathan Amick
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-12 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: &9066640 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *9066640
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: &9063100 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *9063100
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: &9061600 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *9061600
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: &9058580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *9058580
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: &9057040 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *9057040
+- !ruby/object:Gem::Dependency
+  name: guard-spork
+  requirement: &9055460 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *9055460
+description: ObfuscateId is a simple Ruby on Rails plugin that hides your seqential
+  Active Record ids.  Although having nothing to do with security, it can be used
+  to make database record id information non-obvious.
+email:
+- github@nathanamick.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/tasks/obfuscate_id_tasks.rake
+- lib/obfuscate_id/scatter_swap.rb
+- lib/obfuscate_id/run_scatter_swap.rb
+- lib/obfuscate_id/version.rb
+- lib/obfuscate_id.rb
+- MIT-LICENSE
+- Rakefile
+- README.md
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -372583255443185690
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -372583255443185690
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: A simple Rails plugin that lightly masks seqential ActiveRecord ids
+test_files: []