signed_json 0.0.1

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/*
+*.gem
+.bundle

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,31 @@
+PATH
+  remote: .
+  specs:
+    signed_json (0.0.1)
+      json
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    json (1.4.6)
+    rake (0.8.7)
+    rspec (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+      rspec-mocks (~> 2.0.1)
+    rspec-core (2.0.1)
+    rspec-expectations (2.0.1)
+      diff-lcs (>= 1.1.2)
+    rspec-mocks (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  json
+  rake
+  rspec (~> 2.0)
+  signed_json!

data/README.md

@@ -0,0 +1,82 @@
+signed_json
+============
+
+Encodes and decodes data to a JSON string signed with OpenSSL HMAC. Great for signed cookies.
+
+
+Install.
+--------
+    gem install signed_json
+
+
+Use.
+----
+    require 'signed_json'
+    s = SignedJson::Signer.new('your secret')
+
+    ### encode ###
+    s.encode 'a string'
+    s.encode ['an', 'array']
+    s.encode { :a => 'hash' }
+
+    ### decode ###
+    s.decode '["da7555389d05e04a3367b84aed401cafbbecfe3d","example"]'
+    # => "example"
+    s.decode '["da7555389d05e04a3367b84aed401cafbbecfe3d","tampered"]'
+    # SignedJson::SignatureError
+
+
+Understand.
+-----------
+
+`SignedJson::Signer` takes any JSON encodable data, and returns the data in a JSON string along with an [HMAC][1] signature.  The output string can then be decoded back into the original data, with certainty that it was generated using the same secret.
+
+The signature uses [`OpenSSL::HMAC`][2], with the configurable digest defaulting to SHA1.
+
+Note that the data is *not* encrypted - it is clearly readable, but altering the data will cause the signature verification to fail.  The encoded output looks like this:
+
+    ["f47bd6c4108cf503b98b82b2e36ce3e7bae712b5",["an","array","of","strings"]]
+
+This is ideal for signed cookies, and allows client cookies to be used as a light-weight session store.
+
+Rails already has a nice signed cookie implementation, but because [`ActiveSupport::MessageVerifier`][3] uses Base64 encoded Marshal.dump instead of JSON, it is barely portable between Ruby versions, let alone different platforms.
+
+`SignedJson::Signer`, on the other hand, can easily be implemented in other languages, allowing for signed cookies shared between same-domain web applications, for example.
+
+
+  [1]: http://en.wikipedia.org/wiki/HMAC
+  [2]: http://ruby-doc.org/ruby-1.9/classes/OpenSSL/HMAC.html
+  [3]: http://api.rubyonrails.org/classes/ActiveSupport/MessageVerifier.html
+
+
+Status.
+-------
+
+Ported from my PHP implementation, which is running in high-traffic production environments.
+
+RSpec speaks for the Ruby implementation:
+
+    $ rake spec
+    
+    SignedJson
+      round trip encoding/decoding
+        round-trips a string
+        round-trips an array of strings and ints
+        round-trips a hash with string keys, string and int values
+        round-trips a nested array
+        round-trips a hash/array/string/int structure
+      Signer#encode
+        returns a string
+        returns a valid JSON-encoded array
+      Signer#decode error handling
+        raises SignatureError for incorrect key/signature
+        raises InputError for invalid input
+    
+    Finished in 0.0186 seconds
+    9 examples, 0 failures
+
+
+Meh.
+----
+
+(c) 2010 Paul Annesley, MIT license.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+desc "Run specs"
+task :spec do
+  system 'bundle exec rspec --color --format documentation spec/*_spec.rb'
+end

data/lib/signed_json/errors.rb

@@ -0,0 +1,7 @@
+module SignedJson
+
+  class Error < RuntimeError; end
+  class InputError < Error; end
+  class SignatureError < Error; end
+
+end

data/lib/signed_json/version.rb

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

data/lib/signed_json.rb

@@ -0,0 +1,44 @@
+require 'json'
+require 'signed_json/errors'
+
+module SignedJson
+  class Signer
+
+    def initialize(secret, digest = 'SHA1')
+      @secret = secret
+      @digest = digest
+    end
+
+    def encode(input)
+      [digest_for(input), input].to_json
+    end
+
+    def decode(input)
+      digest, data = json_decode(input)
+      raise SignatureError unless digest === digest_for(data)
+      data
+    end
+
+    def digest_for(input)
+      # ActiveSupport::MessageVerifier does this, probably for a good reason.
+      require 'openssl' unless defined?(OpenSSL)
+      OpenSSL::HMAC.hexdigest(OpenSSL::Digest.const_get(@digest).new, @secret, input.to_json)
+    end
+
+    private
+
+    def json_decode(input)
+      begin
+        parts = JSON.parse(input)
+      rescue JSON::ParserError
+        raise InputError
+      end
+
+      raise InputError unless
+        parts.instance_of?(Array) && parts.length == 2
+
+      parts
+    end
+  end
+
+end

data/signed_json.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "signed_json/version"
+
+Gem::Specification.new do |s|
+  s.name        = "signed_json"
+  s.version     = SignedJson::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Paul Annesley"]
+  s.email       = ["paul@annesley.cc"]
+  s.homepage    = "http://github.com/pda/signed_json"
+  s.summary     = %q{Encodes and decodes JSON-encodable data into and from a signed JSON string.}
+
+  s.rubyforge_project = "signed_json"
+
+  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('json')
+
+  s.add_development_dependency('rspec', ['~> 2.0'])
+  s.add_development_dependency('rake')
+end

data/spec/signed_json_spec.rb

@@ -0,0 +1,60 @@
+require 'spec_helper'
+
+describe SignedJson do
+
+  describe "round trip encoding/decoding" do
+
+    it "round-trips a string" do
+      "a string".should round_trip_as_signed_json
+    end
+
+    it "round-trips an array of strings and ints" do
+      [1, 'a', 2, 'b'].should round_trip_as_signed_json
+    end
+
+    it "round-trips a hash with string keys, string and int values" do
+      { 'a' => 'b', 'b' => 2 }.should round_trip_as_signed_json
+    end
+
+    it "round-trips a nested array" do
+      [ 'a', [ 'b', [ 'c', 'd' ], 'e' ], 'f' ].should round_trip_as_signed_json
+    end
+
+    it "round-trips a hash/array/string/int structure" do
+      { 'a' => [ 'b' ], 'd' => { 'e' => 'f' }, 'g' => 10 }.should round_trip_as_signed_json
+    end
+
+  end
+
+  describe "Signer#encode" do
+
+    it "returns a string" do
+      encoded = SignedJson::Signer.new('right').encode('test')
+      encoded.should be_instance_of(String)
+    end
+
+    it "returns a valid JSON-encoded array" do
+      encoded = SignedJson::Signer.new('right').encode('test')
+      JSON.parse(encoded).should be_instance_of(Array)
+    end
+
+  end
+
+  describe "Signer#decode error handling" do
+
+    it "raises SignatureError for incorrect key/signature" do
+      encoded = SignedJson::Signer.new('right').encode('test')
+      lambda {
+        SignedJson::Signer.new('wrong').decode(encoded)
+      }.should raise_error(SignedJson::SignatureError)
+    end
+
+    it "raises InputError for invalid input" do
+      lambda {
+        SignedJson::Signer.new('key').decode('blarg')
+      }.should raise_error(SignedJson::InputError)
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,34 @@
+require 'signed_json'
+
+RSpec::Matchers.define :round_trip_as_signed_json do
+
+  match do |actual|
+
+    signer = SignedJson::Signer.new('some secret')
+
+    @encoded = signer.encode(actual)
+    @decoded = signer.decode(@encoded)
+
+    if @encoded == actual
+      fail_because :not_encoded
+    elsif @decoded != actual
+      fail_because :mismatch
+    else
+      true
+    end
+  end
+
+  def fail_because(reason_code)
+    @reason = reason_code
+    false
+  end
+
+  failure_message_for_should do |actual|
+    if @reason == :not_encoded
+      "Expected encoded to be different to original input: #{actual}"
+    elsif @reason == :mismatch
+      "Expected decoded to equal original input, got '#{@decoded}'"
+    end
+  end
+
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification 
+name: signed_json
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Paul Annesley
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-04 00:00:00 +11:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "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: 
+        - 2
+        - 0
+        version: "2.0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: 
+email: 
+- paul@annesley.cc
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- lib/signed_json.rb
+- lib/signed_json/errors.rb
+- lib/signed_json/version.rb
+- signed_json.gemspec
+- spec/signed_json_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/pda/signed_json
+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: signed_json
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Encodes and decodes JSON-encodable data into and from a signed JSON string.
+test_files: []
+