king_hmac 1.0.0

data/.gitignore

@@ -0,0 +1,4 @@
+nbproject/*
+coverage/*
+rdoc/*
+pkg/*

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Georg Leciejewski
+
+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.rdoc

@@ -0,0 +1,145 @@
+= king-hmac
+
+This gem started with a copy & disection of auth-hmac gem v1.1.1
+
+king-hmac is a Ruby implementation of HMAC[http://en.wikipedia.org/wiki/HMAC]
+based authentication of HTTP requests. HMAC authentication involves a client and
+server having a shared secret key. When sending the request the client, signs
+the request using the secret key. This involves building a canonical
+representation of the request and then generating a HMAC of the request using
+the secret. The generated HMAC is then sent as part of the request.
+
+When the server receives the request it builds the same canonical representation
+and generates a HMAC using it's copy of the secret key, if the HMAC produced by
+the server matches the HMAC sent by the client, the server can be assured that
+the client also possesses the shared secret key.
+
+HMAC based authentication also provides message integrity checking because the
+HMAC is based on a combination of the shared secret and the content of the
+request.  So if any part of the request that is used to build the canonical
+representation is modified by a malicious party or in transit the authentication
+will then fail.
+
+KingHmac::Auth is loosely based on the Amazon Web Services authentication scheme
+but without the Amazon specific components, i.e. it is HMAC for the rest of us.
+
+
+== INSTALL:
+Gem hosted on gemcutter.org
+  sudo gem install king-hmac
+
+== Source Code
+See http://github.com/salesking/king-hmac
+The source repository:
+  git clone git://github.com/salesking/king-hmac.git
+
+== When to use it?
+
+HMAC Authentication is best used as authentication for communication between
+applications such as web services.  It provides better security than HTTP Basic
+authentication without the need to set up SSL. Of course if you need to protect
+the confidentiality of the data then you need SSL, but if you just want to
+authenticate requests without sending credentials in the clear KingHmac::Auth
+is a good choice.
+
+== Usage
+
+The simplest way to use KingHmac::Auth is with the KingHmac::Auth.sign! and
+KingHmac::Auth.authenticate? methods. KingHmac::Auth.sign! takes a HTTP request
+object, an access id and a secret key and signs the request with the access_id
+and secret key.
+
+On the server side you can then authenticate these requests using the
+KingHmac::Auth.authenticated? method. This takes the same arguments as the sign!
+method but returns true if the request has been signed with the access id and
+secret	or false if it hasn't.
+
+If you have more than one set of credentials you might find it useful to create
+an instance of the KingHmac::Auth class, passing your credentials as a Hash of
+access id => secret keys, like so:
+  @hmac_auth = KingHmac::Auth.new('access_id1' => 'secret1', 'access_id2' => 'secret2')
+
+You can then use the instance methods of the @hmac_auth object to sign and
+authenticate requests, for example:
+  @hmac_auth.sign!(request, "access_id1")
+
+Sign +request+ with "access_id1" and it's corresponding secret key.  Similarly
+authentication is done like so:
+  @hmac_auth.authenticated?(request)
+which will return true if the request has been signed with one of the access id
+and secret key pairs provided in the constructor.
+
+=== Supported HTTP request objects
+
+KingHmac::Auth will do its best to figure out which type it is an handle it
+accordingly. 
+* Net::HTTP::HTTPRequest
+* CGI::Request
+* Webrick HTTP request object.
+* Rack::Request
+
+=== access id
+The access_id is used to identify the secret key that was used to sign the
+request. Think of it as like a user name, it allows you to hand out different
+keys to different clients and authenticate each of them individually. The
+access_id is sent in the clear so you should avoid making it an important string.
+
+=== secret key
+The secret key is the shared secret between the client and the server.
+You should make this sufficiently random so that is can't be guessed or exposed
+to dictionary attacks.
+The follow code will give you a pretty good secret key:
+
+  random = File.read('/dev/random', 512)
+  secret_key = Base64.encode64(Digest::SHA2.new(512).digest(random))
+	
+=== Rails Integration
+
+KingHmac::Auth supports authentication within Rails controllers and signing of
+requests generated by Active Resource. See
+KingHmac::Rails::ControllerFilter::ClassMethods and
+KingHmac::Rails::ActiveResourceExtension::BaseHmac::ClassMethods for details.
+
+== How does it work?
+
+When creating a signature for a HTTP request KingHmac::Auth first generates a
+canonical representation of the request. 
+
+This canonical string is created like so:
+
+  canonical_string = HTTP-Verb    + "\n" +
+                   Content-Type + "\n" +
+                   Content-MD5  + "\n" +
+                   Date         + "\n" +
+                   request-uri;
+
+Where Content-Type, Content-MD5 and Date are all taken from the headers of the
+request.  If Content-Type or Content-MD5 are not present, they are substituted
+with an empty string.  If Date is not present it is added to the request headers
+with the value +Time.now.httpdate+.  +request-uri+ is the path component of the
+request, without any query string, i.e. everything up to the ?.
+
+This string is then used with the secret to generate a SHA1 HMAC using the
+following:
+
+  OpenSSL::HMAC.digest(OpenSSL::Digest::Digest.new('sha1'), secret_key, canonical_string)
+
+The result is then Base64 encoded and added to the headers of the request as the
++Authorization+ header in the format:
+  Authorization: KingHmac::Auth <access_id>:<base64 encoded king-hmac>
+
+When authenaticating a request, KingHmac::Auth looks for the Authorization
+header in the above format, parses out the components, regenerates a HMAC for
+the request, using the secret key identified by the access id and then compares
+the generated HMAC with the one provided by the client.  If they match the
+request is authenticated.
+
+Using these details it is possible to build code that will sign and authenticate
+KingHmac::Auth style requests in other languages.
+
+
+== Authors and Contributors
+
+This gem started with a copy & disection of auth-king-hmac gem v1.1.1.
+Most of this doc was written by Sean Geoghegan
+auth-king-hmac was developed by Sean Geoghegan http://rubyforge.org/projects/auth-king-hmac &&  by Peerworks[http://peerworks.org].

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "king_hmac"
+    gem.summary = %Q{A Ruby Gem for authenticating HTTP requests using a HMAC}
+    gem.description = %Q{A Ruby Gem for authenticating HTTP requests using a HMAC}
+    gem.email = "gl@salesking.eu"
+    gem.homepage = "http://github.com/salesking/king_hmac"
+    gem.authors = ["Georg Leciejewski"]
+    gem.add_development_dependency "rspec", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+desc 'Default: run specs.'
+task :default => :spec
+
+spec_files = Rake::FileList["spec/**/*_spec.rb"]
+
+desc "Run specs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = spec_files
+  t.spec_opts = ["-c"]
+end
+
+desc "Generate code coverage"
+Spec::Rake::SpecTask.new(:coverage) do |t|
+  t.spec_files = spec_files
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec,/var/lib/gems']
+end
+
+desc 'Generate king_hmac documentation.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'king_hmac'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/init.rb

@@ -0,0 +1 @@
+require "#{File.dirname(__FILE__)}/lib/king_hmac"

data/king_hmac.gemspec

@@ -0,0 +1,60 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{king_hmac}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Georg Leciejewski"]
+  s.date = %q{2010-04-10}
+  s.description = %q{A Ruby Gem for authenticating HTTP requests using a HMAC}
+  s.email = %q{gl@salesking.eu}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "init.rb",
+     "king_hmac.gemspec",
+     "lib/king_hmac.rb",
+     "lib/king_hmac/auth.rb",
+     "lib/king_hmac/cannonical_string.rb",
+     "lib/king_hmac/headers.rb",
+     "lib/king_hmac/rack/middleware.rb",
+     "lib/king_hmac/rails/active_resource.rb",
+     "lib/king_hmac/rails/controller.rb",
+     "spec/fixtures/credentials.yml",
+     "spec/king_hmac/king_hmac_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/salesking/king_hmac}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{A Ruby Gem for authenticating HTTP requests using a HMAC}
+  s.test_files = [
+    "spec/king_hmac/king_hmac_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 0"])
+  end
+end
+

data/lib/king_hmac/auth.rb

@@ -0,0 +1,143 @@
+module KingHmac
+  # This module provides a HMAC Authentication method for HTTP requests. It should work with
+  # net/http request classes and CGIRequest classes and hence Rails.
+  #
+  # It is loosely based on the Amazon Web Services Authentication mechanism but
+  # generalized to be useful to any application that requires HMAC based authentication.
+  # As a result of the generalization, it won't work with AWS because it doesn't support
+  # the Amazon extension headers.
+  #
+  # === References
+  # Cryptographic Hash functions:: http://en.wikipedia.org/wiki/Cryptographic_hash_function
+  # SHA-1 Hash function::          http://en.wikipedia.org/wiki/SHA-1
+  # HMAC algorithm::               http://en.wikipedia.org/wiki/HMAC
+  # RFC 2104::                     http://tools.ietf.org/html/rfc2104
+  #
+  class Auth
+   
+    include KingHmac::Headers
+   
+
+    @@default_signature_class = KingHmac::CanonicalString
+
+    # Create an KingHmac::Auth instance using the given credential store
+    #
+    # Credential Store:
+    # * Credential store must respond to the [] method and return a secret for access key id
+    # 
+    # Options:
+    # Override default options
+    # *  <tt>:service_id</tt> - Service ID used in the AUTHORIZATION header string. Default is KingHmac::Auth.
+    # *  <tt>:signature_method</tt> - Proc object that takes request and produces the signature string
+    #                                 used for authentication. Default is CanonicalString.
+    # Examples:
+    #   my_hmac = KingHmac::Auth.new('access_id1' => 'secret1', 'access_id2' => 'secret2')
+    #
+    #   cred_store = { 'access_id1' => 'secret1', 'access_id2' => 'secret2' }
+    #   options = { :service_id => 'MyApp', :signature_method => lambda { |r| MyRequestString.new(r) } }
+    #   my_hmac = KingHmac::Auth.new(cred_store, options)
+    #   
+    def initialize(credential_store, options = nil)
+      @credential_store = credential_store
+
+      # Defaults
+      @service_id = self.class.name
+      @signature_class = @@default_signature_class
+
+      unless options.nil?
+        @service_id = options[:service_id] if options.key?(:service_id)
+        @signature_class = options[:signature] if options.key?(:signature) && options[:signature].is_a?(Class)
+      end
+      
+      @signature_method = lambda { |r| @signature_class.send(:new, r) }
+    end
+
+    # Generates canonical signing string for given request
+    #
+    # Supports same options as KingHmac::Auth.initialize for overriding service_id and
+    # signature method.
+    # 
+    def self.canonical_string(request, options = nil)
+      self.new(nil, options).canonical_string(request)
+    end
+
+    # Generates signature string for a given secret
+    #
+    # Supports same options as KingHmac::Auth.initialize for overriding service_id and
+    # signature method.
+    # 
+    def self.signature(request, secret, options = nil)
+      self.new(nil, options).signature(request, secret)
+    end
+
+    # Signs a request using a given access key id and secret.
+    #
+    # Supports same options as KingHmac::Auth.initialize for overriding service_id and
+    # signature method.
+    # 
+    def self.sign!(request, access_key_id, secret, options = nil)
+      credentials = { access_key_id => secret }
+      self.new(credentials, options).sign!(request, access_key_id)
+    end
+    
+    # Authenticates a request using HMAC
+    #
+    # Supports same options as KingHmac::Auth.initialize for overriding service_id and
+    # signature method.
+    # 
+    def self.authenticated?(request, access_key_id, secret, options)
+      credentials = { access_key_id => secret }
+      self.new(credentials, options).authenticated?(request)
+    end
+    
+    # Signs a request using the access_key_id and the secret associated with that id
+    # in the credential store.
+    #
+    # Signing a requests adds an Authorization header to the request in the format:
+    #
+    #  <service_id> <access_key_id>:<signature>
+    #
+    # where <signature> is the Base64 encoded HMAC-SHA1 of the CanonicalString and the secret.
+    #
+    def sign!(request, access_key_id)
+      secret = @credential_store[access_key_id]
+      raise ArgumentError, "No secret found for key id '#{access_key_id}'" if secret.nil?
+      request['Authorization'] = authorization(request, access_key_id, secret)
+    end
+    
+    # Authenticates a request using HMAC
+    #
+    # Returns true if the request has an KingHmac::Auth Authorization header and
+    # the access id and HMAC match an id and HMAC produced for the secret
+    # in the credential store. Otherwise returns false.
+    #
+    def authenticated?(request)
+      rx = Regexp.new("#{@service_id} ([^:]+):(.+)$")
+      if md = rx.match(authorization_header(request))
+        access_key_id = md[1]
+        hmac = md[2]
+        secret = @credential_store[access_key_id]
+        !secret.nil? && hmac == signature(request, secret)
+      else
+        false
+      end
+    end
+
+    def signature(request, secret)
+      digest = OpenSSL::Digest::Digest.new('sha1')
+      Base64.encode64(OpenSSL::HMAC.digest(digest, secret, canonical_string(request))).strip
+    end
+
+    def canonical_string(request)
+      @signature_method.call(request)
+    end
+    
+    def authorization_header(request)
+      find_header(%w(Authorization HTTP_AUTHORIZATION), headers(request))
+    end
+
+    def authorization(request, access_key_id, secret)
+      "#{@service_id} #{access_key_id}:#{signature(request, secret)}"      
+    end
+  end
+end

data/lib/king_hmac/cannonical_string.rb

@@ -0,0 +1,69 @@
+module KingHmac
+  # Build a Canonical String for a HTTP request.
+  #
+  # A Canonical String has the following format:
+  #
+  # CanonicalString = HTTP-Verb    + "\n" +
+  #                   Content-Type + "\n" +
+  #                   Content-MD5  + "\n" +
+  #                   Date         + "\n" +
+  #                   request-uri;
+  #
+  #
+  # If the Date header doesn't exist, one will be generated since
+  # Net/HTTP will generate one if it doesn't exist and it will be
+  # used on the server side to do authentication.
+  #
+  class CanonicalString < String # :nodoc:
+    include Headers
+    
+    def initialize(request)
+      self << request_method(request) + "\n"
+      self << header_values(headers(request)) + "\n"
+      self << request_path(request)
+    end
+    
+    private
+      def request_method(request)
+        if request.respond_to?(:request_method) && request.request_method.is_a?(String)
+          request.request_method
+        elsif request.respond_to?(:method) && request.method.is_a?(String)
+          request.method
+        elsif request.respond_to?(:env) && request.env
+          request.env['REQUEST_METHOD']
+        else
+          raise ArgumentError, "Don't know how to get the request method from #{request.inspect}"
+        end
+      end
+      
+      def header_values(headers)
+        [ content_type(headers),
+          content_md5(headers),
+          (date(headers) or headers['Date'] = Time.now.utc.httpdate)
+        ].join("\n")
+      end
+     
+      def content_type(headers)
+        find_header(%w(CONTENT-TYPE CONTENT_TYPE HTTP_CONTENT_TYPE), headers)
+      end
+      
+      def date(headers)
+        find_header(%w(DATE HTTP_DATE), headers)
+      end
+      
+      def content_md5(headers)
+        find_header(%w(CONTENT-MD5 CONTENT_MD5), headers)
+      end
+      
+      def request_path(request)
+        # Try unparsed_uri in case it is a Webrick request
+        path = if request.respond_to?(:unparsed_uri)
+          request.unparsed_uri
+        else
+          request.path
+        end
+        
+        path[/^[^?]*/]
+      end
+  end
+end

data/lib/king_hmac/headers.rb

@@ -0,0 +1,28 @@
+module KingHmac
+  module Headers # :nodoc:
+    # Gets the headers for a request.
+    #
+    # Attempts to deal with known HTTP header representations in Ruby.
+    # Currently handles net/http and Rails.
+    #
+    def headers(request)
+      if request.respond_to?(:headers)
+        request.headers
+      elsif request.respond_to?(:env) && request.env
+        request.env
+      elsif request.respond_to?(:[])
+        request
+      else
+        raise ArgumentError, "Don't know how to get the headers from #{request.inspect}"
+      end
+    end
+    
+    def find_header(keys, headers)
+      val = keys.map do |key|
+        headers[key]
+      end.compact.first
+      var = 'adsf'
+      val
+    end
+  end
+end

data/lib/king_hmac/rack/middleware.rb

@@ -0,0 +1,44 @@
+require 'rack/request'
+module KingHmac
+  module Rack
+    class Middleware
+
+      # === Parameter
+      # opts<Hash>::
+      # === opts params:
+      # keys<Hash{String=>String}>:: Must be an array of accesskey=> secret
+      # respond to the [] method and return a secret for access key id
+      # only<Array[String]>:: path's to protect
+      def initialize(app, opts={})
+        @app = app
+        @opts = opts
+        @plain_error = "HMAC Authentication failed. Get yourself a valid HMAC Key .. Dude .. or ask your admin to get you some credentials"
+        @hmac_auth = KingHmac::Auth.new(@opts['keys'])
+      end
+
+      def call(env)
+        path = env['PATH_INFO']
+        do_hmac_check = @opts['only'].detect{|i| path.include?(i) }
+        if do_hmac_check
+          unless hmac_authenticated?(::Rack::Request.new(env))
+            headers = {'Content-Type' => "text/plain",
+                      'Content-Length' => "#{@plain_error.length}",
+                      'WWW-Authenticate' => 'AuthHMAC'
+                      }
+            [401, headers, [@plain_error]]
+          else #valid credentials
+            @app.call(env)
+          end
+        else # unprotected
+          @app.call(env)
+        end
+      end
+
+      def hmac_authenticated?(request)
+        @hmac_auth.authenticated?(request)
+      end
+
+
+    end
+  end
+end

data/lib/king_hmac/rails/active_resource.rb

@@ -0,0 +1,99 @@
+module ActiveResourceExtension  # :nodoc:
+  module BaseHmac # :nodoc:
+    def self.included(base)
+      base.extend(ClassMethods)
+
+      base.class_inheritable_accessor :hmac_access_id
+      base.class_inheritable_accessor :hmac_secret
+      base.class_inheritable_accessor :use_hmac
+      base.class_inheritable_accessor :hmac_options
+    end
+
+    module ClassMethods
+      # Call with an Active Resource class definition to sign
+      # all HTTP requests sent by that class with the provided
+      # credentials.
+      #
+      # Can be called with either a hash or two separate parameters
+      # like so:
+      #
+      #   class MyResource < ActiveResource::Base
+      #     with_auth_hmac("my_access_id", "my_secret")
+      #   end
+      #
+      # or
+      #
+      #   class MyOtherResource < ActiveResource::Base
+      #     with_auth_hmac("my_access_id" => "my_secret")
+      #   end
+      #
+      #
+      # This has only been tested with Rails 2.1 and since it is virtually a monkey
+      # patch of the internals of ActiveResource it might not work with past or
+      # future versions.
+      #
+      def with_auth_hmac(access_id, secret = nil, options = nil)
+        if access_id.is_a?(Hash)
+          self.hmac_access_id = access_id.keys.first
+          self.hmac_secret = access_id[self.hmac_access_id]
+        else
+          self.hmac_access_id = access_id
+          self.hmac_secret = secret
+        end
+        self.use_hmac = true
+        self.hmac_options = options
+
+        class << self
+          alias_method_chain :connection, :hmac
+        end
+      end
+
+      def connection_with_hmac(refresh = false) # :nodoc:
+        c = connection_without_hmac(refresh)
+        c.hmac_access_id = self.hmac_access_id
+        c.hmac_secret = self.hmac_secret
+        c.use_hmac = self.use_hmac
+        c.hmac_options = self.hmac_options
+        c
+      end
+    end
+
+    module InstanceMethods # :nodoc:
+    end
+  end
+
+  module Connection # :nodoc:
+    def self.included(base)
+      base.send :alias_method_chain, :request, :hmac
+      base.class_eval do
+        attr_accessor :hmac_secret, :hmac_access_id, :use_hmac, :hmac_options
+      end
+    end
+
+    def request_with_hmac(method, path, *arguments)
+      if use_hmac && hmac_access_id && hmac_secret
+        arguments.last['Date'] = Time.now.httpdate if arguments.last['Date'].nil?
+        temp = "Net::HTTP::#{method.to_s.capitalize}".constantize.new(path, arguments.last)
+        AuthHMAC.sign!(temp, hmac_access_id, hmac_secret, hmac_options)
+        arguments.last['Authorization'] = temp['Authorization']
+      end
+
+      request_without_hmac(method, path, *arguments)
+    end
+  end
+
+  unless defined?(ActiveResource)
+    begin
+      require 'rubygems'
+      gem 'activeresource'
+      require 'activeresource'
+    rescue
+      nil
+    end
+  end
+
+  if defined?(ActiveResource)
+    ActiveResource::Base.send(:include, BaseHmac)
+    ActiveResource::Connection.send(:include, Connection)
+  end
+end