obfuscurity 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Graham Ashton
+
+MIT License
+
+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,116 @@
+# Obfuscurity
+
+Have you ever needed to generate a unique number for a piece of data (a
+little like a primary key) that's exposed to your customers? You might
+use your database's primary key, but you don't want to expose an
+internal counter that could give away sensitive information.
+
+An **order number in a billing system** is a good example; until you've
+processed thousands of orders you won't want people to know just how
+young your business it (in some cases, it doesn't instil confidence).
+
+Or perhaps you don't want your competitors to be able to work out **how
+many people have signed up for your web app**, but want to include a
+customer number in the URL? If you were to use an incrementing field
+from your database, that information becomes painfully apparent.
+
+The obvious solution (generating a random number and checking to see
+whether it's already in use) feels like a hack, and performance starts
+to suffer (because you find yourself generating numbers that have
+already been used) quicker than you might expect.
+
+Luckily, there's an easy solution, as outlined in [this comment][comment]
+on StackOverflow. Just in case you don't have access to StackOverflow
+right now, this is what it says:
+
+> Pick a 8 or 9 digit number at random, say 839712541. Then, take your
+> order number's binary representation (for this example, I'm not using
+> 2's complement), pad it out to the same number of bits (30), reverse it,
+> and xor the flipped order number and the magic number.
+
+[comment]: http://stackoverflow.com/a/612085/158841
+
+(Don't worry if you didn't follow that)
+
+It's rather ingenius, and allows you to take a random seed (e.g.
+839712541) and a incrementing series of numbers, and convert them into a
+seemingly random series. You can then convert them back again simply by
+reversing the approach.
+
+Of course, this **isn't** a secure approach. Anybody with a computer and
+plenty of time would be able to work out the pattern.
+
+If you've got some numbers that you seriously need to protect, use
+cryptography. Obscurity provides [no security at all][wikipedia].
+
+[wikipedia]: http://en.wikipedia.org/wiki/Security_through_obscurity
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'obfuscurity'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install obfuscurity
+
+## Usage
+
+To obfuscate the number you want to hide, make yourself a `Baffler`:
+
+    baffler = Obfuscurity::Baffler.new
+    baffler.obfuscate(1)  # -> 302841629
+    baffler.obfuscate(2)  # -> 571277085
+
+If you later want to convert back to your primary key, use the clarify
+method:
+
+    baffler.clarify(302841629)  # -> 1
+    baffler.clarify(571277085)  # -> 2
+
+The `Baffler` object just happens to convert `1` to `302841629` because
+of the seed that it's using (see the [StackOverflow comment][comment]
+for details).
+
+### Configuring behaviour
+
+If you'd like to use a different sequence specify a different seed when
+you create the `Baffler` instance:
+
+    baffler = Obfuscurity::Baffler.new(seed: 61493749)
+
+You'll no doubt have noticed that the numbers produced by default are
+rather large. The algorithm uses a fixed number of bits (30 by default),
+so any number as large as `2 ** 30` could be returned by the `obfuscate`
+method.
+
+If you know you won't need anything like that many unique numbers you
+can reduce the number of bits:
+
+    baffler = Obfuscurity::Baffler.new(max_bits: 16)
+    baffler.obfuscate(42)  # -> 21505
+
+Just be aware that the maximum number of unique numbers that you can
+cope with is `2 ** max_bits`, or in the case of 16 bits, just 32768
+(which isn't a lot).
+
+If you attempt to obfuscate a number that's too big to fit in the number
+space available (i.e. you exceed the value set for `max_bits`) a
+`Obfuscurity::Error` exception will be raised.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Credits
+
+Thanks to @benlovell for suggesting the name.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/obfuscurity.rb

@@ -0,0 +1,43 @@
+require 'obfuscurity/version'
+
+module Obfuscurity
+  class Error < RuntimeError; end
+
+  class Baffler
+    def initialize(params = {})
+      @seed = params.fetch(:seed, 839712541)
+      @max_bits = params.fetch(:max_bits, 30)
+      check_size_of_number_space(@seed)
+    end
+
+    def obfuscate(number)
+      check_size_of_number_space(number)
+      seed_bits = number_to_bits(@seed)
+      xor_bits = (0 ... seed_bits.size).map { |i| number[i] ^ seed_bits[i] }
+      bits_to_number(xor_bits)
+    end
+
+    def clarify(number)
+      bits = number_to_bits(number ^ @seed)
+      bits_to_number(bits.reverse)
+    end
+
+    private
+      def number_to_bits(number)
+        [].tap do |bits|
+          (@max_bits - 1).downto(0) { |i| bits << number[i] }
+        end
+      end
+
+      def bits_to_number(bits)
+        bits.inject(0) { |result, bit| (result << 1) | bit }
+      end
+
+      def check_size_of_number_space(number)
+        root = number ** (1.0 / @max_bits)
+        if root > 2
+          raise Error.new("#{number} requires more than #{@max_bits} bits")
+        end
+      end
+  end
+end

data/lib/obfuscurity/version.rb

@@ -0,0 +1,3 @@
+module Obfuscurity
+  VERSION = "1.0.0"
+end

data/obfuscurity.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'obfuscurity/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "obfuscurity"
+  gem.version       = Obfuscurity::VERSION
+  gem.authors       = ["Graham Ashton"]
+  gem.email         = ["graham@effectif.com"]
+  gem.description   = <<-EOF
+Sometimes exposing your app's internal counters (e.g. your database's
+auto-incrementing primary keys) to the world is a bad idea. Maybe your
+competitors will be able to work out how many orders you're making per
+week, or your customers will be able to infer how many other customers
+you've got. This gem will allow you to obscure those numbers so you can
+use them in your URLs, your user interface, or as seemingly random order
+numbers.
+  EOF
+  gem.summary       = %q{Obfuscate your database ids, converting them to (seemingly) random numbers}
+  gem.homepage      = "https://github.com/gma/obfuscurity"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_development_dependency('nutrasuite')
+  gem.add_development_dependency('rake')
+end

data/test/obfuscator_test.rb

@@ -0,0 +1,52 @@
+require 'test/unit'
+require 'nutrasuite'
+
+require_relative '../lib/obfuscurity'
+
+class BafflerTest < MiniTest::Unit::TestCase
+  a 'Baffler' do
+    it 'should generate unique (repeatable) number from integer' do
+      # Wondering why the results are 302841629 and 571277085? See this
+      # thread on Stack Overflow:
+      #
+      # http://stackoverflow.com/questions/1179439/best-way-to-generate-order-numbers-for-an-online-store
+
+      2.times do
+        assert_equal 302841629, Obfuscurity::Baffler.new.obfuscate(1)
+      end
+      assert_equal 571277085, Obfuscurity::Baffler.new.obfuscate(2)
+    end
+
+    it 'should convert an obfuscated number back into the original integer' do
+      baffler = Obfuscurity::Baffler.new
+
+      assert_equal 1, baffler.clarify(302841629)
+      assert_equal 2, baffler.clarify(571277085)
+
+      10.times do |i|
+        n = baffler.obfuscate(i)
+        assert_equal i, baffler.clarify(n)
+      end
+    end
+
+    it 'allow you to control the size of the number space' do
+      baffler = Obfuscurity::Baffler.new(max_bits: 16, seed: 1)
+      assert_equal 21505, baffler.obfuscate(42)
+    end
+
+    it "should ensure that seed doesn't exceed available bits" do
+      max_bits = 30
+      too_big = (2 ** max_bits) + 1
+      assert_raises(Obfuscurity::Error) do
+        Obfuscurity::Baffler.new(max_bits: max_bits, seed: too_big)
+      end
+    end
+
+    it "should ensure that obscured numbers don't exceed available bits" do
+      baffler = Obfuscurity::Baffler.new
+      assert_raises(Obfuscurity::Error) do
+        baffler.obfuscate((2 ** 30) + 1)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: obfuscurity
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Graham Ashton
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nutrasuite
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! 'Sometimes exposing your app''s internal counters (e.g. your database''s
+
+  auto-incrementing primary keys) to the world is a bad idea. Maybe your
+
+  competitors will be able to work out how many orders you''re making per
+
+  week, or your customers will be able to infer how many other customers
+
+  you''ve got. This gem will allow you to obscure those numbers so you can
+
+  use them in your URLs, your user interface, or as seemingly random order
+
+  numbers.
+
+'
+email:
+- graham@effectif.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/obfuscurity.rb
+- lib/obfuscurity/version.rb
+- obfuscurity.gemspec
+- test/obfuscator_test.rb
+homepage: https://github.com/gma/obfuscurity
+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: 2796161447218621274
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 2796161447218621274
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Obfuscate your database ids, converting them to (seemingly) random numbers
+test_files:
+- test/obfuscator_test.rb