signature 0.1.3 → 0.1.4

data/.travis.yml

@@ -7,5 +7,9 @@ rvm:
   - jruby-19mode # JRuby in 1.9 mode
   - rbx-18mode
   - rbx-19mode
+matrix:
+  allow_failures:
+    - rvm: rbx-18mode
+    - rvm: rbx-19mode
 
 script: bundle exec rspec spec

data/Gemfile.lock

@@ -6,7 +6,14 @@ PATH
 GEM
   remote: http://rubygems.org/
   specs:
+    bacon (1.1.0)
     diff-lcs (1.1.3)
+    em-spec (0.2.6)
+      bacon
+      eventmachine
+      rspec (> 2.6.0)
+      test-unit
+    eventmachine (0.12.10)
     rspec (2.9.0)
       rspec-core (~> 2.9.0)
       rspec-expectations (~> 2.9.0)
@@ -15,10 +22,12 @@ GEM
     rspec-expectations (2.9.1)
       diff-lcs (~> 1.1.3)
     rspec-mocks (2.9.0)
+    test-unit (2.4.4)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  em-spec
   rspec (~> 2.9.0)
   signature!

data/lib/signature.rb

@@ -34,59 +34,134 @@ module Signature
 
       @method = method.upcase
       @path, @query_hash, @auth_hash = path, query_hash, auth_hash
+      @signed = false
     end
 
+    # Sign the request with the given token, and return the computed
+    # authentication parameters
+    #
     def sign(token)
       @auth_hash = {
         :auth_version => "1.0",
         :auth_key => token.key,
         :auth_timestamp => Time.now.to_i.to_s
       }
-
       @auth_hash[:auth_signature] = signature(token)
 
+      @signed = true
+
       return @auth_hash
     end
 
     # Authenticates the request with a token
     #
-    # Timestamp check: Unless timestamp_grace is set to nil (which will skip
-    # the timestamp check), an exception will be raised if timestamp is not
-    # supplied or if the timestamp provided is not within timestamp_grace of
-    # the real time (defaults to 10 minutes)
+    # Raises an AuthenticationError if the request is invalid.
+    # AuthenticationError exception messages are designed to be exposed to API
+    # consumers, and should help them correct errors generating signatures
+    #
+    # Timestamp: Unless timestamp_grace is set to nil (which allows this check
+    # to be skipped), AuthenticationError will be raised if the timestamp is
+    # missing or further than timestamp_grace period away from the real time
+    # (defaults to 10 minutes)
     #
-    # Signature check: Raises an exception if the signature does not match the
-    # computed value
+    # Signature: Raises AuthenticationError if the signature does not match
+    # the computed HMAC. The error contains a hint for how to sign.
     #
     def authenticate_by_token!(token, timestamp_grace = 600)
+      # Validate that your code has provided a valid token. This does not
+      # raise an AuthenticationError since passing tokens with empty secret is
+      # a code error which should be fixed, not reported to the API's consumer
+      if token.secret.nil? || token.secret.empty?
+        raise "Provided token is missing secret"
+      end
+
       validate_version!
       validate_timestamp!(timestamp_grace)
       validate_signature!(token)
       true
     end
 
+    # Authenticate the request with a token, but rather than raising an
+    # exception if the request is invalid, simply returns false
+    #
     def authenticate_by_token(token, timestamp_grace = 600)
       authenticate_by_token!(token, timestamp_grace)
     rescue AuthenticationError
       false
     end
 
-    def authenticate(timestamp_grace = 600, &block)
+    # Authenticate a request
+    #
+    # Takes a block which will be called with the auth_key from the request,
+    # and which should return a Signature::Token (or nil if no token can be
+    # found for the key)
+    #
+    # Raises errors in the same way as authenticate_by_token!
+    #
+    def authenticate(timestamp_grace = 600)
+      raise ArgumentError, "Block required" unless block_given?
       key = @auth_hash['auth_key']
-      raise AuthenticationError, "Authentication key required" unless key
+      raise AuthenticationError, "Missing parameter: auth_key" unless key
       token = yield key
-      unless token && token.secret
-        raise AuthenticationError, "Invalid authentication key"
+      unless token
+        raise AuthenticationError, "Unknown auth_key"
       end
       authenticate_by_token!(token, timestamp_grace)
       return token
     end
 
+    # Authenticate a request asynchronously
+    #
+    # This method is useful it you're running a server inside eventmachine and
+    # need to lookup the token asynchronously.
+    #
+    # The block is passed an auth key and a deferrable which should succeed
+    # with the token, or fail if the token cannot be found
+    #
+    # This method returns a deferrable which succeeds with the valid token, or
+    # fails with an AuthenticationError which can be used to pass the error
+    # back to the user
+    #
+    def authenticate_async(timestamp_grace = 600)
+      raise ArgumentError, "Block required" unless block_given?
+      df = EM::DefaultDeferrable.new
+
+      key = @auth_hash['auth_key']
+
+      unless key
+        df.fail(AuthenticationError.new("Missing parameter: auth_key"))
+        return
+      end
+
+      token_df = yield key
+      token_df.callback { |token|
+        begin
+          authenticate_by_token!(token, timestamp_grace)
+          df.succeed(token)
+        rescue AuthenticationError => e
+          df.fail(e)
+        end
+      }
+      token_df.errback {
+        df.fail(AuthenticationError.new("Unknown auth_key"))
+      }
+    ensure
+      return df
+    end
+
+    # Expose the authentication parameters for a signed request
+    #
     def auth_hash
-      raise "Request not signed" unless @auth_hash && @auth_hash[:auth_signature]
+      raise "Request not signed" unless @signed
       @auth_hash
     end
 
+    # Query parameters merged with the computed authentication parameters
+    #
+    def signed_params
+      @query_hash.merge(auth_hash)
+    end
+
     private
 
       def signature(token)

data/lib/signature/version.rb

@@ -1,3 +1,3 @@
 module Signature
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/signature.gemspec

@@ -19,4 +19,5 @@ Gem::Specification.new do |s|
 
   s.add_dependency "jruby-openssl" if defined?(JRUBY_VERSION)
   s.add_development_dependency "rspec", "~> 2.9.0"
+  s.add_development_dependency "em-spec"
 end

data/spec/signature_spec.rb

@@ -10,72 +10,81 @@ describe Signature do
       "query" => "params",
       "go" => "here"
     })
-    @signature = @request.sign(@token)[:auth_signature]
   end
 
-  it "should generate base64 encoded signature from correct key" do
-    @request.send(:string_to_sign).should == "POST\n/some/path\nauth_key=key&auth_timestamp=1234&auth_version=1.0&go=here&query=params"
-    @signature.should == '3b237953a5ba6619875cbb2a2d43e8da9ef5824e8a2c689f6284ac85bc1ea0db'
-  end
+  describe "generating signatures" do
+    before :each do
+      @signature = "3b237953a5ba6619875cbb2a2d43e8da9ef5824e8a2c689f6284ac85bc1ea0db"
+    end
 
-  it "should make auth_hash available after request is signed" do
-    request = Signature::Request.new('POST', '/some/path', {
-      "query" => "params"
-    })
-    lambda {
-      request.auth_hash
-    }.should raise_error('Request not signed')
-
-    request.sign(@token)
-    request.auth_hash.should == {
-      :auth_signature => "da078fcedd72941b6c873caa40d0d6b2000ebfc700cee802b128dd20f72e74e9",
-      :auth_version => "1.0",
-      :auth_key => "key",
-      :auth_timestamp => '1234'
-    }
-  end
+    it "should generate signature correctly" do
+      @request.sign(@token)
+      string = @request.send(:string_to_sign)
+      string.should == "POST\n/some/path\nauth_key=key&auth_timestamp=1234&auth_version=1.0&go=here&query=params"
 
-  it "should cope with symbol keys" do
-    @request.query_hash = {
-      :query => "params",
-      :go => "here"
-    }
-    @request.sign(@token)[:auth_signature].should == @signature
-  end
+      digest = OpenSSL::Digest::SHA256.new
+      signature = OpenSSL::HMAC.hexdigest(digest, @token.secret, string)
+      signature.should == @signature
+    end
 
-  it "should cope with upcase keys (keys are lowercased before signing)" do
-    @request.query_hash = {
-      "Query" => "params",
-      "GO" => "here"
-    }
-    @request.sign(@token)[:auth_signature].should == @signature
-  end
+    it "should make auth_hash available after request is signed" do
+      @request.query_hash = {
+        "query" => "params"
+      }
+      lambda {
+        @request.auth_hash
+      }.should raise_error('Request not signed')
 
-  it "should use the path to generate signature" do
-    @request.path = '/some/other/path'
-    @request.sign(@token)[:auth_signature].should_not == @signature
-  end
+      @request.sign(@token)
+      @request.auth_hash.should == {
+        :auth_signature => "da078fcedd72941b6c873caa40d0d6b2000ebfc700cee802b128dd20f72e74e9",
+        :auth_version => "1.0",
+        :auth_key => "key",
+        :auth_timestamp => '1234'
+      }
+    end
 
-  it "should use the query string keys to generate signature" do
-    @request.query_hash = {
-      "other" => "query"
-    }
-    @request.sign(@token)[:auth_signature].should_not == @signature
-  end
+    it "should cope with symbol keys" do
+      @request.query_hash = {
+        :query => "params",
+        :go => "here"
+      }
+      @request.sign(@token)[:auth_signature].should == @signature
+    end
+
+    it "should cope with upcase keys (keys are lowercased before signing)" do
+      @request.query_hash = {
+        "Query" => "params",
+        "GO" => "here"
+      }
+      @request.sign(@token)[:auth_signature].should == @signature
+    end
 
-  it "should use the query string values to generate signature" do
-    @request.query_hash = {
-      "key" => "notfoo",
-      "other" => 'bar'
-    }
-    @request.sign(@token)[:signature].should_not == @signature
+    it "should use the path to generate signature" do
+      @request.path = '/some/other/path'
+      @request.sign(@token)[:auth_signature].should_not == @signature
+    end
+
+    it "should use the query string keys to generate signature" do
+      @request.query_hash = {
+        "other" => "query"
+      }
+      @request.sign(@token)[:auth_signature].should_not == @signature
+    end
+
+    it "should use the query string values to generate signature" do
+      @request.query_hash = {
+        "key" => "notfoo",
+        "other" => 'bar'
+      }
+      @request.sign(@token)[:signature].should_not == @signature
+    end
   end
 
   describe "verification" do
     before :each do
-      Time.stub!(:now).and_return(Time.at(1234))
       @request.sign(@token)
-      @params = @request.query_hash.merge(@request.auth_hash)
+      @params = @request.signed_params
     end
 
     it "should verify requests" do
@@ -148,6 +157,15 @@ describe Signature do
       }.should raise_error('Version not supported')
     end
 
+    it "should validate that the provided token has a non-empty secret" do
+      token = Signature::Token.new('key', '')
+      request = Signature::Request.new('POST', '/some/path', @params)
+
+      lambda {
+        request.authenticate_by_token!(token)
+      }.should raise_error('Provided token is missing secret')
+    end
+
     describe "when used with optional block" do
       it "should optionally take a block which yields the signature" do
         request = Signature::Request.new('POST', '/some/path', @params)
@@ -162,14 +180,83 @@ describe Signature do
         request = Signature::Request.new('POST', '/some/path', @params)
         lambda {
           request.authenticate { |key| nil }
-        }.should raise_error('Authentication key required')
+        }.should raise_error('Missing parameter: auth_key')
       end
 
       it "should raise error if block returns nil (i.e. key doesn't exist)" do
         request = Signature::Request.new('POST', '/some/path', @params)
         lambda {
           request.authenticate { |key| nil }
-        }.should raise_error('Invalid authentication key')
+        }.should raise_error('Unknown auth_key')
+      end
+
+      it "should raise unless block given" do
+        request = Signature::Request.new('POST', '/some/path', @params)
+        lambda {
+          request.authenticate
+        }.should raise_error(ArgumentError, "Block required")
+      end
+    end
+
+    describe "authenticate_async" do
+      include EM::SpecHelper
+      default_timeout 1
+
+      it "returns a deferrable which succeeds if authentication passes" do
+        request = Signature::Request.new('POST', '/some/path', @params)
+        em {
+          df = EM::DefaultDeferrable.new
+
+          request_df = request.authenticate_async do |key|
+            df
+          end
+
+          df.succeed(@token)
+
+          request_df.callback { |token|
+            token.should == @token
+            done
+          }
+        }
+      end
+
+      it "returns a deferrable which fails if block df fails" do
+        request = Signature::Request.new('POST', '/some/path', @params)
+        em {
+          df = EM::DefaultDeferrable.new
+
+          request_df = request.authenticate_async do |key|
+            df
+          end
+
+          df.fail()
+
+          request_df.errback { |e|
+            e.class.should == Signature::AuthenticationError
+            e.message.should == 'Unknown auth_key'
+            done
+          }
+        }
+      end
+
+      it "returns a deferrable which fails if request does not validate" do
+        request = Signature::Request.new('POST', '/some/path', @params)
+        em {
+          df = EM::DefaultDeferrable.new
+
+          request_df = request.authenticate_async do |key|
+            df
+          end
+
+          token = Signature::Token.new('key', 'wrong_secret')
+          df.succeed(token)
+
+          request_df.errback { |e|
+            e.class.should == Signature::AuthenticationError
+            e.message.should =~ /Invalid signature/
+            done
+          }
+        }
       end
     end
   end

data/spec/spec_helper.rb

@@ -1,9 +1,8 @@
-$LOAD_PATH.unshift(File.dirname(__FILE__))
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-
-require 'rubygems'
 require 'signature'
+
 require 'rspec'
+require 'em-spec/rspec'
 
 RSpec.configure do |config|
   

metadata

@@ -1,35 +1,62 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: signature
-version: !ruby/object:Gem::Version
-  version: 0.1.3
+version: !ruby/object:Gem::Version 
+  hash: 3713544621248369165
   prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 4
+  version: 0.1.4
 platform: ruby
-authors:
+authors: 
 - Martyn Loughran
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-06 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
+
+date: 2012-08-15 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
   name: rspec
-  requirement: &70163026801480 !ruby/object:Gem::Requirement
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        hash: 1156501143490752456
+        segments: 
+        - 2
+        - 9
+        - 0
         version: 2.9.0
   type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: em-spec
   prerelease: false
-  version_requirements: *70163026801480
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 2002549777813010636
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
 description: Simple key/secret based authentication for apis
-email:
+email: 
 - me@mloughran.com
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
-- .document
+
+files: 
 - .gitignore
 - .travis.yml
 - Gemfile
@@ -37,7 +64,6 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- VERSION
 - lib/signature.rb
 - lib/signature/version.rb
 - signature.gemspec
@@ -45,29 +71,37 @@ files:
 - spec/spec_helper.rb
 homepage: http://github.com/mloughran/signature
 licenses: []
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 2002549777813010636
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 2002549777813010636
+      segments: 
+      - 0
+      version: "0"
 requirements: []
+
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.12
 signing_key: 
 specification_version: 3
 summary: Simple key/secret based authentication for apis
-test_files:
+test_files: 
 - spec/signature_spec.rb
 - spec/spec_helper.rb
-has_rdoc: 

data/.document

@@ -1,5 +0,0 @@
-README.rdoc
-lib/**/*.rb
-bin/*
-features/**/*.feature
-LICENSE

data/VERSION

@@ -1 +0,0 @@
-0.1.1