warden-hmac-authentication 0.2.0

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2011 Florian Gilcher <florian.gilcher@asquera.de>, Felix Gilcher <felix.gilcher@asquera.de>
+
+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,298 @@
+# HMAC
+
+This gem provides request authentication via [HMAC](http://en.wikipedia.org/wiki/Hmac). The main usage is request based, noninteractive
+authentication for API implementations. Two strategies are supported that differ mainly in how the authentication information is
+transferred to the server: One header-based authentication method and one query-based. The authentication scheme is in some parts based
+on ideas laid out in this article and the following discussion: 
+http://broadcast.oreilly.com/2009/12/principles-for-standardized-rest-authentication.html
+
+The gem also provides a small helper class that can be used to generate request signatures.
+
+## Header-Based authentication
+
+The header-based authentication transports the authentication information in the (misnamed) `Authorization` HTTP-Header. The primary 
+advantage of header-based authentication is that request urls are stable even if authentication information changes. The improves
+cacheability of the resource.
+
+Header-based authentication is supported by the `:hmac_header` strategy.
+
+## Query-Based authentication
+
+Query-Based authentication encodes all authentication in the query string. Query-based authentication has unique advantages in 
+scenarios with little or no control over the request headers such as pre-generating and embedding a signed URL in a web-page or 
+similar cases. However, resources requested using query-based authentication cannot be cached since the request URL changes for
+every request.
+All information related to authentication is passed as a single hash in one single query parameter to minimize collisions with other
+query parameters. The name of the query parameter defaults to `auth` and can be controlled using the `:auth_parameter` config option.
+Query-based authentication takes optional headers into account if they are present in the request.
+
+Query-based authentication is supported by the `:hmac_query` strategy.
+
+## Shared secret
+
+Both strategies use a secret that is shared between the server and the client to calculate the signature. The secret must be
+configured when registering the strategy. For simple cases a single secret may be sufficient but most real-world scenarios
+will require a different secret for each possible client. Such cases can be managed by passing a Proc as secret. An empty
+secret (empty string or nil) will trigger authentication failure.
+
+
+## Warden strategy usage
+
+Both strategies can be used at the same time and will not interfere with each other. It is advisable to attempt query-based
+authentication first to reduce the chance that a stray Authorization header triggers header-based authentication. Both strategies
+read additional configuration from a hash named :hmac in the warden scope.
+
+Configure the HMAC warden strategy:
+
+    use Warden::Manager do |manager|
+      manager.failure_app = -> env { [401, {"Content-Length" => "0"}, [""]] }
+      # other scopes
+      manager.scope_defaults :hmac,  :strategies => [:hmac_query, :hmac_header], 
+                                     :hmac => { 
+                                       :secret => "secrit"
+                                     }
+    end
+
+
+
+### Retrieving the secret from a database or other storage
+
+If you want to retrieve the secret and token using a different strategy, either extend the HMAC strategy:
+
+    class Warden::Strategies::HMACQuery < Warden::Strategies::HMACBase
+      def retrieve_user
+        User.get(request[:user_id])
+      end
+
+      def secret
+        retrieve_user.secret
+      end
+    end
+
+or use a Proc that retrieves the secret.
+
+    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|
+                                         "secret"
+                                       }
+                                     }
+    end
+
+### Controlling the HMAC algorithm
+
+The algorithm can be controlled using the `:algorithm` option:
+
+    use Warden::Manager do |manager|
+      manager.failure_app = -> env { [401, {"Content-Length" => "0"}, [""]] }
+      # other scopes
+      manager.scope_defaults :hmac, :strategies => [:hmac_query, :hmac_header], 
+                                     :hmac => { 
+                                       :secret => "secrit",
+                                       :algorithm => "md5"
+                                     }
+    end
+
+The algorithm defaults to SHA1.
+
+## Auth Scheme Name
+
+The name of the authentication scheme is primarily used for header authentication. It is used to construct the `Authorization` header and 
+must thus avoid names that are reserved for existing standardized authentication schemes such as `Basic` and `Digest`. The scheme
+name is also used to construct the default values for various header names. The authentication scheme name defaults to `HMAC`
+
+    use Warden::Manager do |manager|
+      manager.failure_app = -> env { [401, {"Content-Length" => "0"}, [""]] }
+      # other scopes
+      manager.scope_defaults :hmac, :strategies => [:hmac_query, :hmac_header], 
+                                     :hmac => { 
+                                       :secret => "secrit",
+                                       :auth_scheme_name => "MyScheme"
+                                     }
+    end
+
+No authentication attempt is made if the scheme name in the `Authorization` header does not match the configured scheme name.    
+
+## 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
+advisable to limit the length of the nonce to a reasonable value. If a nonce is used it should be changed with every request. The
+default header for the nonce is `X-#{auth-scheme-name}-Nonce` (`X-HMAC-Nonce`). The header name can be controlled using the `:nonce_header` 
+configuration option.
+
+The `:require_nonce` configuration can be set to `true` to enforce a nonce. If a nonce is required no authentication attempt will be
+made for requests not providing a nonce.
+
+    use Warden::Manager do |manager|
+      manager.failure_app = -> env { [401, {"Content-Length" => "0"}, [""]] }
+      # other scopes
+      manager.scope_defaults :hmac, :strategies => [:hmac_query, :hmac_header], 
+                                     :hmac => { 
+                                       :secret => "secrit",
+                                       :require_nonce => true
+                                     }
+    end
+
+
+## Required headers and parameters
+
+Required headers and parameters must be present for a successful authentication attempt. The list of required headers defaults to 
+the `Authorization` header for header-based authentication and is empty for query-based authentication. The list of required
+parameters defaults to the chosen authentication parameter for query-based authentication and is empty for header-based authentication.
+If a required parameter or header is not included in the request, no authentication attempt will be made for the strategy.
+
+## Other optional headers
+
+Some headers are optional but should be included in the signature of the request if present. The default list of optional headers
+includes `Content-MD5` and `Content-Type`. The list of optional headers can be configured using the `:optional_headers` config option.
+Optional headers are always included in the canonical representation if they are found in the request and not blank. Optional headers
+will be included in the canonical representation for query-based authentication if they are present in the request so be careful 
+not to include any header that is out of your clients control.
+
+## Date and TTL
+
+It is good practice to enforce a max-age for tokens. The hmac strategy allows this via the `ttl` parameter. It controls the max age 
+of tokens in seconds and defaults to 900 seconds. Pass `nil` as ttl value to disable TTL checking.
+
+The timestamp of the request is usually passed in the `Date` HTTP-Header. However, since some HTTP-Client libraries do not allow 
+setting the Date header another header may be used to override the `Date` header. The name of this header can be controlled via the
+`:alternate_date_header` option and defaults to `X-#{auth-scheme-name}-Date` (`X-HMAC-Date`). 
+
+The date must be formatted as HTTP-Date according to RFC 1123, section 5.2.14 and should be provided in GMT time.
+
+Example: Setting the ttl to 300 seconds:
+
+    use Warden::Manager do |manager|
+      manager.failure_app = -> env { [401, {"Content-Length" => "0"}, [""]] }
+      # other scopes
+      manager.scope_defaults :token, :strategies => [:hmac_query, :hmac_header], 
+                                     :hmac => { 
+                                       :secret => "secrit",
+                                       :ttl => 300 # make tokens valid for 5 minutes
+                                     }
+    end
+
+### Clock Skew
+
+The TTL allows for a little clock skew to accommodate servers that are slightly running off time. The allowed clock skew can be 
+controlled with the `:clockskew` option and defaults to 5 seconds.
+
+
+## Canonical representation
+
+Both request methods use a canonical representation of the request together with the shared secret to calculate a signature 
+that authenticates the request. The canonical representation is calculated using the following algorithm:
+
+* Start with the empty string ("")
+* Add the HTTP-Verb for the request ("GET", "POST", ...) in capital letters, followed by a single newline (U+000A).
+* Add the date for the request using the form "date:#{date-of-request}" followed by a single newline. The date for the signature must be
+formatted exactly as in the request.
+* Add the nonce for the request in the form "nonce:#{nonce-in-request}" followed by a single newline. If no nonce is passed use the
+empty string as nonce value.
+* Convert all remaining header names to lowercase.
+* Sort the remaining headers lexicographically by header name.
+* Trim header values by removing any whitespace before the first non-whitespace character and after the last non-whitespace character.
+* Combine lowercase header names and header values using a single colon (“:”) as separator. Do not include whitespace characters 
+around the separator.
+* Combine all headers using a single newline (U+000A) character and append them to the canonical representation, 
+followed by a single newline (U+000A) character.
+* Append the url-decoded query path to the canonical representation
+* URL-decode query parameters if required
+* If using query-based authentication: Remove all authentication-related parameters from the query parameters.
+* Sort all query parameters lexicographically by parameter name and join them, using a single ampersand (“&”) as separator
+* Append the query string using a single question mark (“?”) as separator unless the query string is empty
+
+### Examples
+
+Given the following request:
+
+    GET /example/resource.html?sort=header%20footer&order=ASC HTTP/1.1
+    Host: www.example.org
+    Date: Mon, 20 Jun 2011 12:06:11 GMT
+    User-Agent: curl/7.20.0 (x86_64-pc-linux-gnu) libcurl/7.20.0 OpenSSL/1.0.0a zlib/1.2.3
+    X-MAC-Nonce: Thohn2Mohd2zugoo
+
+The canonical representation is:
+
+    GET\n
+    date:Mon, 20 Jun 2011 12:06:11 GMT\n
+    nonce:Thohn2Mohd2zugo\n
+    /example/resource.html?order=ASC&sort=header footer
+
+
+Given the following request:
+
+    GET /example/resource.html?sort=header%20footer&order=ASC HTTP/1.1
+    Host: www.example.org
+    Date: Mon, 20 Jun 2011 12:06:11 GMT
+    User-Agent: curl/7.20.0 (x86_64-pc-linux-gnu) libcurl/7.20.0 OpenSSL/1.0.0a zlib/1.2.3
+    X-MAC-Nonce: Thohn2Mohd2zugoo
+    X-MAC-Date: Mon, 20 Jun 2011 14:06:57 GMT
+
+The canonical representation is:
+
+    GET\n
+    date:Mon, 20 Jun 2011 14:06:57 GMT\n
+    nonce:Thohn2Mohd2zugo\n
+    /example/resource.html?order=ASC&sort=header footer
+
+
+### Generating the canonical representation for query-based authentication
+
+The canonical representation for query-based authentication is generated using the same algorithm as for header-based authentication, but some
+of the values are retrieved from the query string instead of the respective headers. All query parameters related to authentication
+must be removed from the query string before generating the canonical representation.
+
+#### Example
+
+Given the following request:
+
+    GET /example/resource.html?page=3&order=id%2casc&auth%5Bnonce%5D=foLiequei7oosaiWun5aoy8oo&auth%5Bdate%5D=Mon%2C+20+Jun+2011+14%3A06%3A57+GMT HTTP/1.1
+    Host: www.example.org
+    Date: Mon, 20 Jun 2011 12:06:11 GMT
+    User-Agent: curl/7.20.0 (x86_64-pc-linux-gnu) libcurl/7.20.0 OpenSSL/1.0.0a zlib/1.2.3
+
+The canonical representation is:
+
+    GET\n 
+    date:Mon, 20 Jun 2011 14:06:57 GMT\n
+    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.sign_url('http://example.org/example.html', 'secret')
+    h.validate_url_signature('http://example.org/example.html?auth[signature]=foo', 'secret')
+    
+## Licence
+
+Copyright (c) 2011 Florian Gilcher <florian.gilcher@asquera.de>, Felix Gilcher <felix.gilcher@asquera.de>
+
+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/Rakefile

@@ -0,0 +1,10 @@
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+  test.ruby_opts = ['-rubygems', '-rtest_helper']
+end
+
+task :default => :test

data/lib/hmac_signer.rb

@@ -0,0 +1,234 @@
+require 'addressable/uri'
+require 'openssl'
+require 'rack/utils'
+
+
+# Helper class that provides signing capabilites for the hmac strategies.
+#
+# @author Felix Gilcher <felix.gilcher@asquera.de>
+class HMACSigner
+  attr_accessor :secret, :algorithm, :default_opts
+
+  # create a new HMAC instance
+  #
+  # @param [String] algorithm   The hashing-algorithm to use. See the openssl documentation for valid values.
+  # @param [Hash] default_opts  The default options for all calls that take opts
+  #
+  # @option default_opts [String]             :auth_scheme ('HMAC')   The name of the authorization scheme used in the Authorization header and to construct various header-names
+  # @option default_opts [String]             :auth_param ('auth')   The name of the authentication param to use for query based authentication
+  # @option default_opts [String]             :auth_header ('Authorization') The name of the authorization header to use
+  # @option default_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 default_opts [String]             :nonce_header ('X-#{auth_scheme}-Nonce') The header name for the request nonce
+  # @option default_opts [String]             :alternate_date_header ('X-#{auth_scheme}-Date') The header name for the alternate date header
+  # @option default_opts [Bool]               :query_based (false) Whether to use query based authentication
+  # @option default_opts [Bool]               :use_alternate_date_header (false) Use the alternate date header instead of `Date`
+  #
+  def initialize(algorithm = "sha1", default_opts = {})
+    self.algorithm = algorithm
+    self.default_opts = {
+      :auth_scheme => "HMAC",
+      :auth_param => "auth",
+      :auth_header => "Authorization",
+      :auth_header_format => "%{auth_scheme} %{signature}",
+      :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
+    }.merge(default_opts)
+    
+  end
+  
+  # Generate the signature from a hash representation
+  #
+  # @param [Hash] params the parameters to create the representation with
+  # @option params [String] :secret The secret to generate the signature with
+  # @option params [String] :method The HTTP Verb of the request
+  # @option params [String] :date The date of the request as it was formatted in the request
+  # @option params [String] :nonce ('') The nonce given in the request
+  # @option params [String] :path The path portion of the request
+  # @option params [Hash]   :query ({}) The query parameters given in the request. Must not contain the auth param.
+  # @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 [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
+  # @option params [String]             :alternate_date_header ('X-#{auth_scheme}-Date') The header name for the alternate date header
+  # @option params [Bool]               :query_based (false) Whether to use query based authentication
+  # @option params [Bool]               :use_alternate_date_header (false) Use the alternate date header instead of `Date`
+  #
+  # @return [String] the signature
+  def generate_signature(params)
+    secret = params.delete(:secret)
+    OpenSSL::HMAC.hexdigest(algorithm, secret, canonical_representation(params))
+  end
+  
+  # compares the given signature with the signature created from a hash representation
+  #
+  # @param [String] signature the signature to compare with
+  # @param [Hash] params the parameters to create the representation with
+  # @option params [String] :secret The secret to generate the signature with
+  # @option params [String] :method The HTTP Verb of the request
+  # @option params [String] :date The date of the request as it was formatted in the request
+  # @option params [String] :nonce ('') The nonce given in the request
+  # @option params [String] :path The path portion of the request
+  # @option params [Hash]   :query ({}) The query parameters given in the request. Must not contain the auth param.
+  # @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 [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
+  # @option params [String]             :alternate_date_header ('X-#{auth_scheme}-Date') The header name for the alternate date header
+  # @option params [Bool]               :query_based (false) Whether to use query based authentication
+  # @option params [Bool]               :use_alternate_date_header (false) Use the alternate date header instead of `Date`
+  #
+  # @return [Bool] true if the signature matches
+  def validate_signature(signature, params)
+    signature == generate_signature(params)
+  end
+  
+  # convienience method to check the signature of a url with query-based authentication
+  #
+  # @param [String] url the url to test
+  # @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
+  #
+  # @return [Bool] true if the signature is valid
+  def validate_url_signature(url, secret, opts = {})
+    opts = default_opts.merge(opts)
+    opts[:query_based] = true
+    
+    uri = Addressable::URI.parse(url)
+    query_values = uri.query_values
+    auth_params = query_values.delete(opts[:auth_param])
+    
+    date = auth_params["date"]
+    nonce = auth_params["nonce"]
+    validate_signature(auth_params["signature"], :secret => secret, :method => "GET", :path => uri.path, :date => date, :nonce => nonce, :query => query_values, :headers => {})
+  end
+  
+  # generates the canonical representation for a given request
+  # 
+  # @param [Hash] params the parameters to create the representation with
+  # @option params [String] :method The HTTP Verb of the request
+  # @option params [String] :date The date of the request as it was formatted in the request
+  # @option params [String] :nonce ('') The nonce given in the request
+  # @option params [String] :path The path portion of the request
+  # @option params [Hash]   :query ({}) The query parameters given in the request. Must not contain the auth param.
+  # @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 [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
+  # @option params [String] :alternate_date_header ('X-#{auth_scheme}-Date') The header name for the alternate date header
+  # @option params [Bool]   :query_based (false) Whether to use query based authentication
+  # @option params [Bool]   :use_alternate_date_header (false) Use the alternate date header instead of `Date`
+  #
+  # @return [String] the canonical representation
+  def canonical_representation(params)
+    rep = ""
+    
+    rep << "#{params[:method].upcase}\n" 
+    rep << "date:#{params[:date]}\n"
+    rep << "nonce:#{params[:nonce]}\n"
+    
+    (params[:headers] || {}).sort.each do |pair|
+      name,value = *pair
+      rep << "#{name.downcase}:#{value}\n"
+    end
+    
+    rep << params[:path]
+    
+    p = (params[:query] || {}).dup
+    
+    if !p.empty?
+      query = p.sort.map do |key, value|
+        "%{key}=%{value}" % {
+          :key => Rack::Utils.unescape(key.to_s),
+          :value => Rack::Utils.unescape(value.to_s)
+        }
+      end.join("&")
+      rep << "?#{query}"
+    end
+    
+    rep
+  end
+  
+  # sign the given request
+  #
+  # @param [String] url     The url of the request
+  # @param [String] secret  The shared secret for the signature
+  # @param [Hash]   opts    Options for the signature generation
+  #
+  # @option opts [String]             :nonce ('')           The nonce to use in the signature
+  # @option opts [String, #strftime]  :date (Time.now)      The date to use in the signature
+  # @option opts [Hash]               :headers ({})         A list of optional headers to include in the signature
+  #                                   
+  # @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 [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
+  # @option opts [String]             :alternate_date_header ('X-#{auth_scheme}-Date') The header name for the alternate date header
+  # @option opts [Bool]               :query_based (false) Whether to use query based authentication
+  # @option opts [Bool]               :use_alternate_date_header (false) Use the alternate date header instead of `Date`
+  #
+  def sign_request(url, secret, opts = {})
+    opts = default_opts.merge(opts)
+    
+    uri = Addressable::URI.parse(url)
+    headers = opts[:headers] || {}
+    
+    date = opts[:date] || Time.now.gmtime
+    date = date.gmtime.strftime('%a, %e %b %Y %T GMT') if date.respond_to? :strftime
+    
+    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 = {
+        "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
+    else
+      headers[opts[:auth_header]]   = opts[:auth_header_format] % opts.merge({:signature => signature})
+      headers[opts[:nonce_header]]  = opts[:nonce] unless opts[:nonce].nil?
+      
+      if opts[:use_alternate_date_header] 
+        headers[opts[:alternate_date_header]] = date
+      else
+        headers["Date"] = date
+      end
+    end
+    
+    [headers, uri.to_s]
+  end
+  
+  # convienience method to sign a url for use with query-based authentication
+  #
+  # @param [String] url the url to sign
+  # @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
+  #
+  # @return [String] The signed url
+  def sign_url(url, secret, opts = {})
+    opts = default_opts.merge(opts)
+    opts[:query_based] = true
+    
+    headers, url = *sign_request(url, secret, opts)
+    url  
+  end
+  
+  
+end
+

data/lib/strategies/base.rb

@@ -0,0 +1,173 @@
+require 'hmac_signer'
+require 'warden'
+
+
+# Base class for hmac authentication in warden. Provides shared methods such as config access
+# and various helpers.
+#
+# @author Felix Gilcher <felix.gilcher@asquera.de>
+class Warden::Strategies::HMACBase < Warden::Strategies::Base
+  
+
+  # Performs authentication. Calls success! if authentication was performed successfully and halt!
+  # if the authentication information is invalid.
+  #
+  # Delegates parts of the work to signature_valid? which must be implemented in child-strategies.
+  #
+  # @see https://github.com/hassox/warden/wiki/Strategies
+  def authenticate!
+    if "" == secret.to_s
+      debug("authentication attempt with an empty secret")
+      return fail!("Cannot authenticate with an empty secret")
+    end
+    
+    if check_ttl? && !timestamp_valid?
+      debug("authentication attempt with an invalid timestamp. Given was #{timestamp}, expected was #{Time.now.gmtime}")
+      return fail!("Invalid timestamp")  
+    end
+    
+    if signature_valid?
+      success!(retrieve_user)
+    else
+      debug("authentication attempt with an invalid signature.")
+      fail!("Invalid token passed")
+    end
+  end
+  
+  # Retrieve the current request method
+  #
+  # @return [String] The request method in capital letters
+  def request_method
+    env['REQUEST_METHOD'].upcase
+  end
+  
+  # Retrieve the request query parameters
+  #
+  # @return [Hash] The query parameters
+  def params
+    request.GET
+  end
+  
+  # Retrieve the request headers. Header names are normalized by this method by stripping
+  # the `HTTP_`-prefix and replacing underscores with dashes. `HTTP_X_Foo` is normalized to
+  # `X-Foo`.
+  #
+  # @return [Hash] The request headers
+  def headers
+    pairs = env.select {|k,v| k.start_with? 'HTTP_'}
+        .collect {|pair| [pair[0].sub(/^HTTP_/, '').gsub(/_/, '-'), pair[1]]}
+        .sort
+     headers = Hash[*pairs.flatten]
+     headers   
+  end
+  
+  # Retrieve a user from the database. Stub implementation that just returns true, needed for compat.
+  #
+  # @return [Bool] true
+  def retrieve_user
+    true
+  end
+  
+  # Log a debug message if a logger is available.
+  #
+  # @param [String] msg The message to log
+  def debug(msg)
+    if logger
+      logger.debug(msg)
+    end
+  end
+  
+  # Retrieve a logger. Current implementation can
+  # only handle Padrino loggers
+  #
+  # @return [Logger] the logger, nil if none is available
+  def logger
+    if defined? Padrino
+      Padrino.logger
+    end
+  end
+  
+  private
+    def config
+      env["warden"].config[:scope_defaults][scope][:hmac]
+    end
+    
+    def auth_param
+      config[:auth_param] || "auth"
+    end
+    
+    def auth_header
+      config[:auth_header] || "Authorization"
+    end
+    
+    def auth_scheme_name
+      config[:auth_scheme] || "HMAC"
+    end
+    
+    def nonce_header_name
+      config[:nonce_header] || "X-#{auth_scheme_name}-Nonce"
+    end
+    
+    def alternate_date_header_name
+      config[:alternate_date_header] || "X-#{auth_scheme_name}-Date"
+    end
+
+    def optional_headers
+      (config[:optional_headers] || []) + ["Content-MD5", "Content-Type"]
+    end
+    
+    def lowercase_headers
+
+      if @lowercase_headers.nil?
+        tmp = headers.map do |name,value|
+          [name.downcase, value]
+        end
+        @lowercase_headers = Hash[*tmp.flatten]
+      end
+
+      @lowercase_headers
+    end
+    
+    def hmac
+      HMACSigner.new(algorithm)
+    end
+    
+    def algorithm
+      config[:algorithm] || "sha1"
+    end
+    
+    def ttl
+      config[:ttl].to_i
+    end
+    
+    def check_ttl?
+      !config[:ttl].nil?
+    end
+
+    def timestamp
+      Time.strptime(request_timestamp, '%a, %e %b %Y %T %z') unless request_timestamp.nil?
+    end
+    
+    def has_timestamp?
+      !timestamp.nil?
+    end
+    
+    def timestamp_valid?
+      now = Time.now.gmtime.to_i
+      timestamp.to_i <= (now + clockskew) && timestamp.to_i >= (now - ttl)
+    end
+    
+    def nonce_required?
+      !!config[:require_nonce]
+    end
+    
+    def secret
+      @secret ||= config[:secret].respond_to?(:call) ? config[:secret].call(self) : config[:secret]
+    end
+    
+    def clockskew
+      (config[:clockskew] || 5)
+    end
+    
+    
+end

data/lib/strategies/hmac_header_strategy.rb

@@ -0,0 +1,94 @@
+require_relative 'base'
+
+# Implements header-based hmac authentication for warden. The strategy is registered as
+# `:hmac_header` in the warden strategy list.
+#
+# @author Felix Gilcher <felix.gilcher@asquera.de>
+class Warden::Strategies::HMACHeader < Warden::Strategies::HMACBase
+  
+  # Checks that this strategy applies. Tests that the required
+  # authentication information was given.
+  #
+  # @return [Bool] true if all required authentication information is available in the request
+  # @see https://github.com/hassox/warden/wiki/Strategies
+  def valid?
+    valid = required_headers.all? { |h| headers.include?(h) } && headers.include?("Authorization") && has_timestamp?
+    valid = valid && scheme_valid?
+    valid
+  end
+  
+  # Check that the signature given in the request is valid.
+  #
+  # @return [Bool] true if the request is valid
+  def signature_valid?
+    
+    #:method => "GET",
+    #:date => "Mon, 20 Jun 2011 12:06:11 GMT",
+    #:nonce => "TESTNONCE",
+    #:path => "/example",
+    #:query => {
+    #  "foo" => "bar",
+    #  "baz" => "foobared"
+    #},
+    #:headers => {
+    #  "Content-Type" => "application/json;charset=utf8",
+    #  "Content-MD5" => "d41d8cd98f00b204e9800998ecf8427e"
+    #}
+    
+    hmac.validate_signature(given_signature, {
+      :secret => secret,
+      :method => request_method,
+      :date => request_timestamp,
+      :nonce => nonce,
+      :path => request.path,
+      :query => params,
+      :headers => headers.select {|name, value| optional_headers.include? name}
+    })
+  end
+
+  # retrieve the signature from the request
+  #
+  # @return [String] The signature from the request
+  def given_signature
+    headers[auth_header].split(" ")[1]
+  end
+
+  # retrieve the nonce from the request
+  #
+  # @return [String] The nonce or an empty string if no nonce was given in the request
+  def nonce
+    headers[nonce_header_name]
+  end
+
+  # retrieve the request timestamp as string
+  #
+  # @return [String] The request timestamp or an empty string if no timestamp was given in the request
+  def request_timestamp
+    headers[date_header]
+  end
+  
+  private
+    
+    def required_headers
+      headers = [auth_header]
+      headers += [nonce_header_name] if nonce_required? 
+      headers
+    end
+
+    def scheme_valid?
+      headers[auth_header].to_s.split(" ").first == auth_scheme_name
+    end
+    
+    def date_header
+      if headers.include? alternate_date_header_name
+        alternate_date_header_name
+      else
+        "Date"
+      end
+    end
+    
+
+      
+end
+
+Warden::Strategies.add(:hmac_header, Warden::Strategies::HMACHeader)

data/lib/strategies/hmac_query_strategy.rb

@@ -0,0 +1,52 @@
+require_relative 'base'
+
+
+# Implements query-based hmac authentication for warden. The strategy is registered as
+# `:hmac_query` in the warden strategy list.
+#
+# @author Felix Gilcher <felix.gilcher@asquera.de>
+class Warden::Strategies::HMACQuery < Warden::Strategies::HMACBase
+  
+  # Checks that this strategy applies. Tests that the required
+  # authentication information was given.
+  #
+  # @return [Bool] true if all required authentication information is available in the request
+  # @see https://github.com/hassox/warden/wiki/Strategies
+  def valid?
+    valid = auth_info.include? "signature"
+    valid = valid && has_timestamp? if check_ttl?
+    valid = valid && has_nonce? if nonce_required?
+    valid
+  end
+
+  # Check that the signature given in the request is valid.
+  #
+  # @return [Bool] true if the request is valid
+  def signature_valid?
+    hmac.validate_url_signature(request.url, secret)
+  end
+  
+  # retrieve the authentication information from the request
+  #
+  # @return [Hash] the authentication info in the request
+  def auth_info
+    params[auth_param] || {}
+  end
+  
+  # retrieve the nonce from the request
+  #
+  # @return [String] The nonce or an empty string if no nonce was given in the request
+  def nonce
+    auth_info["nonce"] || ""
+  end
+  
+  # retrieve the request timestamp as string
+  #
+  # @return [String] The request timestamp or an empty string if no timestamp was given in the request
+  def request_timestamp
+    auth_info["date"] || ""
+  end
+      
+end
+
+Warden::Strategies.add(:hmac_query, Warden::Strategies::HMACQuery)

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification 
+name: warden-hmac-authentication
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Felix Gilcher
+- Florian Gilcher
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-16 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: addressable
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rack
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rdiscount
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: simplecov
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: simplecov-html
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id006
+description: |-
+  This gem provides request authentication via [HMAC](http://en.wikipedia.org/wiki/Hmac). The main usage is request based, noninteractive
+    authentication for API implementations. Two strategies are supported that differ mainly in how the authentication information is
+    transferred to the server: One header-based authentication method and one query-based. The authentication scheme is in some parts based
+    on ideas laid out in this article and the following discussion: 
+    http://broadcast.oreilly.com/2009/12/principles-for-standardized-rest-authentication.html
+  
+    The gem also provides a small helper class that can be used to generate request signatures.
+email: 
+- felix.gilcher@asquera.de
+- florian.gilcher@asquera.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- Rakefile
+- LICENSE
+- lib/strategies/hmac_query_strategy.rb
+- lib/strategies/hmac_header_strategy.rb
+- lib/strategies/base.rb
+- lib/hmac_signer.rb
+has_rdoc: true
+homepage: https://github.com/Asquera/warden-hmac-authentication
+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"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Provides request based, non-interactive authentication for APIs
+test_files: []
+