warden-hmac-authentication 0.4.0 → 0.5.0

data/README.md

@@ -117,6 +117,13 @@ name is also used to construct the default values for various header names. The
 
 No authentication attempt is made if the scheme name in the `Authorization` header does not match the configured scheme name.    
 
+## Authentication Header Format
+
+The format of the Authentication Header can be controlled using the `:auth_header_format` directive. The given format string will be interpolated
+with all given options and the signature. The default value is `%{auth_scheme} %{signature}` which will result in an auth header with a format such as `HMAC 539263f4f83878a4917d2f9c1521320c28b926a9`. 
+
+The `:auth_header_format` directive has a companion directive, `:auth_header_parse` which can be a proc or a regular expression. Any given regular expression will be evaluated against the string and any named capture pattern will be added to the parameters for the request. The regular expression must at least contain a pattern named `scheme` and pattern named `signature`. The default value is `/(?<scheme>\w+) (?<signature>\w+)/`
+
 ## Optional nonce
 
 An optional nonce can be passed in the request to increase security. The nonce is not limited to digits and can be any string. It's
@@ -263,16 +270,89 @@ The canonical representation is:
     nonce:foLiequei7oosaiWun5aoy8oo\n
     /example/resource.html?order=id,asc&page=3
 
-
 ## HMACSigner usage
 
 The HMACSigner class can be used to validate and generate signatures for a given request. Most methods accept a hash as an intermediate 
 representation of the request but some methods accept and operate on full urls.
 
-    h = HMACSigner.new
+    h = HMAC::Signer.new
     h.sign_url('http://example.org/example.html', 'secret')
     h.validate_url_signature('http://example.org/example.html?auth[signature]=foo', 'secret')
-    
+
+## Using multiple authentication secrets
+
+Most applications will need to authenticate users using a combination of a user-identifier and and associated secret. 
+
+
+### Header-Based Authentication
+
+The format of the Autorization header can be controlled using the `:auth_header_format` option, the regular expression used to parse can be
+set using `:auth_header_parse`. Combining these two options with a proc that retrieves the signing key from a storage authentication with multiple
+secrets allows us to implement multiple signing keys:
+
+
+    use Warden::Manager do |manager|
+      manager.failure_app = -> env { [401, {"Content-Length" => "0"}, [""]] }
+      # other scopes
+      manager.scope_defaults :hmac, :strategies => [:hmac_query, :hmac_header], 
+                                     :store => false, 
+							         :hmac => {
+							           :secret => Proc.new {|strategy|
+							             keys = {
+							               "KEY1" => 'secrit',
+							               "KEY2" => "foo"
+							             }
+               
+							             access_key_id = strategy.parsed_auth_header["access_key_id"]
+							             keys[access_key_id]
+							           },
+							           :auth_header_format => '%{scheme} %{access_key_id} %{signature}',
+							           :auth_header_parse => /(?<scheme>\w+) (?<access_key_id>\w+) (?<signature>\w+)/
+							         }
+    end
+
+This combination of settings uses a slightly different Format for the authorization header and transports the secret keys ID in the header of the form `HMAC KEY2 a59456da1f61f86e96622e283780f58b7428c892`
+
+Another option would be transporting the access key id in a separate header.
+
+### Query-Based Authentication
+
+The same result can be achieved using query-based auth by injecting extra authentication parameters and retrieving the access key in the proc. Given a url such as `http://example.org/example.html?auth[signature]=foo&auth[access_key_id]=KEY2` the following configuration will validate the signature with the secret `foo`:
+
+    use Warden::Manager do |manager|
+      manager.failure_app = -> env { [401, {"Content-Length" => "0"}, [""]] }
+      # other scopes
+      manager.scope_defaults :hmac, :strategies => [:hmac_query, :hmac_header], 
+                                     :store => false, 
+							         :hmac => {
+							           :secret => Proc.new {|strategy|
+							             keys = {
+							               "KEY1" => 'secrit',
+							               "KEY2" => "foo"
+							             }
+               
+							             access_key_id = strategy.params["auth"]["access_key_id"]
+							             keys[access_key_id]
+							           }
+							         }
+    end
+
+To simplify the generation of such urls, the `HMAC::Signer` accepts an `:extra_auth_params` option for query based authentication. Parameters passed via this option will be injected in the auth hash. Parameters injected in the auth hash via this option will not be part of the signature, so only parameters that control the generation of the signature should be placed here.
+
+
+    h.sign_url('http://example.org/example.html', 'foo', {:extra_auth_params => {"access_key_id" => "KEY2"}})
+
+
+## Faraday Middleware
+
+The library includes a faraday middleware that can be used to sign requests made with the faraday http lib. The middleware accepts the same list of options as the HMAC::Signer class.
+
+    Faraday.new(:url => "http://example.com") do |builder|
+      builder.use      Faraday::Request::Hmac, secret, {:extra_auth_params => {"access_key_id" => "KEY2"}}
+      builder.response :raise_error
+      builder.adapter  :net_http
+    end
+
 ## Licence
 
 Copyright (c) 2011 Florian Gilcher <florian.gilcher@asquera.de>, Felix Gilcher <felix.gilcher@asquera.de>

data/bin/warden-hmac-authentication

@@ -1,54 +1,16 @@
 #!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'warden-hmac-authentication' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
 
-require 'trollop'
-require 'hmac/signer'
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
 
-opts = Trollop::options do
-  
-  version "warden-hmac-sign 0.3.0 (c) 2011 Felix Gilcher, Florian Gilcher"
-    banner <<-EOS
-  warden-hmac-authentication is used to create and validate signed urls for
-  usage with the HMAC authentication scheme used by 
-  https://github.com/Asquera/warden-hmac-authentication
+require 'rubygems'
+require 'bundler/setup'
 
-  Usage:
-         warden-hmac-authentication [options] <command> url
-  
-  where command is one of
-  
-    sign: signs the given url 
-    validate: validates the given url
-    
-  and where [options] are:
-  
-  EOS
-  
-  opt :algorithm, "The hashing algorithm to use for the HMAC", :type => :string, :default => "sha1"
-  opt :secret, "The shared secret for the HMAC", :type => :string, :required => true
-  opt :"auth-param", "The name for the auth param in the url", :default => "auth"
-  opt :"date", "The date to use for the signature (defaults to now)"
-end
-
-cmd = ARGV.shift
-Trollop::die "You must give a command" if cmd.nil?
-Trollop::die "You command must be one of [sign, validate]" unless ["sign", "validate"].include? cmd
-Trollop::die "You must provide a URL" if ARGV.empty?
-url = ARGV.shift
-
-secret = opts.delete(:secret)
-algorithm = opts.delete(:algorithm)
-
-signer = HMAC::Signer.new(algorithm)
-
-if "sign" == cmd
-  puts signer.sign_url(url, secret, opts)
-else
-  success = signer.validate_url_signature(url, secret, opts)
-  if success
-    puts "URL #{url} is valid"
-    exit 0
-  else
-    puts "URL #{url} does not contain a valid signature"
-    exit 1
-  end
-end
+load Gem.bin_path('warden-hmac-authentication', 'warden-hmac-authentication')

data/lib/faraday/request/hmac.rb

@@ -0,0 +1,47 @@
+require 'faraday'
+require 'hmac/signer'
+
+module Faraday
+  class Request::Hmac < Faraday::Middleware
+      
+    # create a new Hmac middleware instance
+    #
+    # @param [Object] app           The url of the request
+    # @param [String] secret        The shared secret for the signature
+    # @param [Hash]   options       Options for the signature generation
+    #
+    # @option options [String]             :nonce ('')           The nonce to use in the signature
+    # @option options [String, #strftime]  :date (Time.now)      The date to use in the signature
+    # @option options [Hash]               :headers ({})         A list of optional headers to include in the signature
+    #                       
+    # @option options [String]             :auth_scheme ('HMAC')   The name of the authorization scheme used in the Authorization header and to construct various header-names
+    # @option options [String]             :auth_param ('auth')   The name of the authentication param to use for query based authentication
+    # @option options [Hash]               :extra_auth_params ({}) Additional parameters to inject in the auth parameter
+    # @option options [String]             :auth_header ('Authorization') The name of the authorization header to use
+    # @option options [String]             :auth_header_format ('%{auth_scheme} %{signature}') The format of the authorization header. Will be interpolated with the given options and the signature.
+    # @option options [String]             :nonce_header ('X-#{auth_scheme}-Nonce') The header name for the request nonce
+    # @option options [String]             :alternate_date_header ('X-#{auth_scheme}-Date') The header name for the alternate date header
+    # @option options [Bool]               :query_based (false) Whether to use query based authentication
+    # @option options [Bool]               :use_alternate_date_header (false) Use the alternate date header instead of `Date`
+    #
+    def initialize(app, secret, options = {})
+      @app, @secret, @options, @query_values = app, secret, options
+    end
+  
+    def call(env)
+      sign(env)
+      @app.call(env)
+    end
+  
+    def sign(env)
+      signer = HMAC::Signer.new
+      url = env[:url]
+      headers, url = *signer.sign_request(url, @secret, @options)
+        
+      env[:request_headers] = (env[:request_headers] || {}).merge(headers)
+      env[:url] = Addressable::URI.parse(url)
+      env
+    end
+      
+  end
+end

data/lib/hmac/signer.rb

@@ -36,7 +36,8 @@ module HMAC
         :nonce_header => "X-%{scheme}-Nonce" % {:scheme => (default_opts[:auth_scheme] || "HMAC")},
         :alternate_date_header => "X-%{scheme}-Date" % {:scheme => (default_opts[:auth_scheme] || "HMAC")},
         :query_based => false,
-        :use_alternate_date_header => false
+        :use_alternate_date_header => false,
+        :extra_auth_params => {}
       }.merge(default_opts)
     
     end
@@ -55,6 +56,7 @@ module HMAC
     # @option params [Hash]   :headers ({}) All headers given in the request (optional and required)
     # @option params [String]             :auth_scheme ('HMAC')   The name of the authorization scheme used in the Authorization header and to construct various header-names
     # @option params [String]             :auth_param ('auth')   The name of the authentication param to use for query based authentication
+    # @option params [Hash]               :extra_auth_params ({}) Additional parameters to inject in the auth parameter
     # @option params [String]             :auth_header ('Authorization') The name of the authorization header to use
     # @option params [String]             :auth_header_format ('%{auth_scheme} %{signature}') The format of the authorization header. Will be interpolated with the given options and the signature.
     # @option params [String]             :nonce_header ('X-#{auth_scheme}-Nonce') The header name for the request nonce
@@ -87,6 +89,7 @@ module HMAC
     # @option params [Hash]   :headers ({}) All headers given in the request (optional and required)
     # @option params [String]             :auth_scheme ('HMAC')   The name of the authorization scheme used in the Authorization header and to construct various header-names
     # @option params [String]             :auth_param ('auth')   The name of the authentication param to use for query based authentication
+    # @option params [Hash]               :extra_auth_params ({}) Additional parameters to inject in the auth parameter
     # @option params [String]             :auth_header ('Authorization') The name of the authorization header to use
     # @option params [String]             :auth_header_format ('%{auth_scheme} %{signature}') The format of the authorization header. Will be interpolated with the given options and the signature.
     # @option params [String]             :nonce_header ('X-#{auth_scheme}-Nonce') The header name for the request nonce
@@ -132,6 +135,7 @@ module HMAC
     # @option params [Hash]   :headers ({}) All headers given in the request (optional and required)
     # @option params [String] :auth_scheme ('HMAC')   The name of the authorization scheme used in the Authorization header and to construct various header-names
     # @option params [String] :auth_param ('auth')   The name of the authentication param to use for query based authentication
+    # @option params [Hash]   :extra_auth_params ({}) Additional parameters to inject in the auth parameter
     # @option params [String] :auth_header ('Authorization') The name of the authorization header to use
     # @option params [String] :auth_header_format ('%{auth_scheme} %{signature}') The format of the authorization header. Will be interpolated with the given options and the signature.
     # @option params [String] :nonce_header ('X-#{auth_scheme}-Nonce') The header name for the request nonce
@@ -181,6 +185,7 @@ module HMAC
     #                                   
     # @option opts [String]             :auth_scheme ('HMAC')   The name of the authorization scheme used in the Authorization header and to construct various header-names
     # @option opts [String]             :auth_param ('auth')   The name of the authentication param to use for query based authentication
+    # @option opts [Hash]               :extra_auth_params ({}) Additional parameters to inject in the auth parameter
     # @option opts [String]             :auth_header ('Authorization') The name of the authorization header to use
     # @option opts [String]             :auth_header_format ('%{auth_scheme} %{signature}') The format of the authorization header. Will be interpolated with the given options and the signature.
     # @option opts [String]             :nonce_header ('X-#{auth_scheme}-Nonce') The header name for the request nonce
@@ -200,12 +205,12 @@ module HMAC
       signature = generate_signature(:secret => secret, :method => "GET", :path => uri.path, :date => date, :nonce => opts[:nonce], :query => uri.query_values, :headers => opts[:headers])
       
       if opts[:query_based]
-        auth_params = {
+        auth_params = opts[:extra_auth_params].merge({
           "date" => date,
           "signature" => signature
-        }
+        })
         auth_params[:nonce] = opts[:nonce] unless opts[:nonce].nil?
-      
+        
         query_values =  uri.query_values || {}
         query_values[opts[:auth_param]] = auth_params
         uri.query_values = query_values
@@ -229,7 +234,8 @@ module HMAC
     # @param [String] secret the secret used to sign the url
     # @param [Hash] opts Options controlling the singature generation
     #
-    # @option opts [String] :auth_param ('auth')   The name of the authentication param to use for query based authentication
+    # @option opts [String] :auth_param ('auth')    The name of the authentication param to use for query based authentication
+    # @option opts [Hash]   :extra_auth_params ({}) Additional parameters to inject in the auth parameter
     #
     # @return [String] The signed url
     def sign_url(url, secret, opts = {})

data/lib/hmac/strategies/base.rb

@@ -118,6 +118,10 @@ module Warden
           def optional_headers
             (config[:optional_headers] || []) + ["Content-MD5", "Content-Type"]
           end
+          
+          def auth_header_parse
+            config[:auth_header_parse] || /(?<scheme>\w+) (?<signature>\w+)/
+          end
     
           def lowercase_headers
 

data/lib/hmac/strategies/header.rb

@@ -53,7 +53,20 @@ module Warden
         #
         # @return [String] The signature from the request
         def given_signature
-          headers[auth_header].split(" ")[1]
+          parsed_auth_header['signature']
+        end
+
+        # parses the authentication header from the request using the
+        # regexp or proc given in the :auth_header_parse option. The result 
+        # is memoized
+        #
+        # @return [Hash] The parsed header
+        def parsed_auth_header
+          if @parsed_auth_header.nil?
+            @parsed_auth_header = auth_header_parse.match(headers[auth_header]) || {}
+          end
+          
+          @parsed_auth_header
         end
 
         # retrieve the nonce from the request
@@ -79,7 +92,7 @@ module Warden
           end
 
           def scheme_valid?
-            headers[auth_header].to_s.split(" ").first == auth_scheme_name
+            parsed_auth_header['scheme'] == auth_scheme_name
           end
     
           def date_header

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: warden-hmac-authentication
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -14,7 +14,7 @@ date: 2011-12-13 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
-  requirement: &2152266240 !ruby/object:Gem::Requirement
+  requirement: &2156860860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152266240
+  version_requirements: *2156860860
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &2152265520 !ruby/object:Gem::Requirement
+  requirement: &2156860040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +33,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152265520
+  version_requirements: *2156860040
 - !ruby/object:Gem::Dependency
   name: trollop
-  requirement: &2152265000 !ruby/object:Gem::Requirement
+  requirement: &2156858860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +44,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152265000
+  version_requirements: *2156858860
 - !ruby/object:Gem::Dependency
   name: warden
-  requirement: &2152264180 !ruby/object:Gem::Requirement
+  requirement: &2156858380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,10 +55,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152264180
+  version_requirements: *2156858380
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2152263320 !ruby/object:Gem::Requirement
+  requirement: &2156857780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -66,10 +66,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152263320
+  version_requirements: *2156857780
 - !ruby/object:Gem::Dependency
   name: rack-test
-  requirement: &2152262180 !ruby/object:Gem::Requirement
+  requirement: &2156857300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -77,10 +77,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152262180
+  version_requirements: *2156857300
 - !ruby/object:Gem::Dependency
   name: riot
-  requirement: &2152261120 !ruby/object:Gem::Requirement
+  requirement: &2156856800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -88,10 +88,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152261120
+  version_requirements: *2156856800
 - !ruby/object:Gem::Dependency
   name: timecop
-  requirement: &2152228000 !ruby/object:Gem::Requirement
+  requirement: &2156856220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -99,10 +99,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152228000
+  version_requirements: *2156856220
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &2152227480 !ruby/object:Gem::Requirement
+  requirement: &2156843320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -110,10 +110,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152227480
+  version_requirements: *2156843320
 - !ruby/object:Gem::Dependency
   name: simplecov-html
-  requirement: &2152226940 !ruby/object:Gem::Requirement
+  requirement: &2156842780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -121,7 +121,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152226940
+  version_requirements: *2156842780
 description: ! "This gem provides request authentication via [HMAC](http://en.wikipedia.org/wiki/Hmac).
   The main usage is request based, noninteractive\n  authentication for API implementations.
   Two strategies are supported that differ mainly in how the authentication information
@@ -141,6 +141,7 @@ files:
 - README.md
 - Rakefile
 - LICENSE
+- lib/faraday/request/hmac.rb
 - lib/hmac/signer.rb
 - lib/hmac/strategies/base.rb
 - lib/hmac/strategies/header.rb