hawk-auth 0.0.0 → 0.1.0

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 1.9.2
+  - rbx-19mode
+  - 1.8.7
+  - ree

data/README.md

@@ -1,74 +1,7 @@
-# Hawk
+# Hawk [![Build Status](https://travis-ci.org/tent/hawk-ruby.png)](https://travis-ci.org/tent/hawk-ruby)
 
 Ruby implementation of [Hawk HTTP authentication scheme](https://github.com/hueniverse/hawk).
 
-**Authorization Request Header**
-
-```
-Authorization: Hawk id="{credentials id}", ts="{epoch timestamp}", nonce="{nonce}", hash="{hash}", ext="{ext}", mac="{mac}", app="{application id}", d1g="{d1g}"
-```
-
-`hash`, `ext`, `app`, and `d1g` should only be included if used in mac function.
-
-**Authorization Response Header**
-
-```
-Server-Authorization: Hawk mac="{mac}", hash="{hash}", ext="{ext}"
-```
-
-`mac` is constructed using the same params as in the request with the exception of `hash` and `ext` which are replaced with new values.
-
-`hash` and `ext` are both optional.
-
-**MAC Function**
-
-```
-base-64(
-  hmac-{algorithm (e.g. sha-256)}(
-    hawk.{hawk version}.{type}
-    {epoch timestamp}
-    {nonce}
-    {uppercase request method}
-    {lowercase request path}
-    {lowercase request host}
-    {request port}
-    {hash (see below) or empty line}
-    {ext (optional)}
-    {application id (optional)}
-    {application id digest (requires application id)}
-  )
-)
-```
-
-**Payload Hash Function**
-
-```
-base-64(
-  digest-{algorithm (e.g. sha-256)}(
-    hawk.#{hawk version}.payload
-    {plain content-type (e.g. application/json)}
-    {request payload or empty line}
-  )
-)
-```
-
-**Bewit MAC Function**
-
-```
-base-64(
-  {credentials id} + \ + {expiry epoch timestamp} + \ + hmac-{algorithm (e.g. sha-256)}(
-    hawk.{hawk version}.bewit
-    {epoch timestamp}
-    {nonce}
-    {uppercase request method}
-    {lowercase request path}
-    {lowercase request host}
-    {request port}
-    {ext (optional)}
-  ) + \ + {ext or empty}
-)
-```
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -85,7 +18,96 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: write usage instructions
+```
+$ irb
+> require 'hawk'
+
+> Hawk::Client.build_authorization_header(
+>   :credentials => {
+>     :id => '123456',
+>     :key => '2983d45yun89q',
+>     :algorithm => 'sha256'
+>   },
+>   :ts => 1365898519,
+>   :method => 'POST',
+>   :path => '/somewhere/over/the/rainbow',
+>   :host => 'example.net',
+>   :port => 80,
+>   :payload => 'something to write about',
+>   :ext => 'Bazinga!',
+>   :nonce => 'Ygvqdz'
+> )
+Hawk id="123456", ts="1365898519", nonce="Ygvqdz", hash="LjRmtkSKTW0ObTUyZ7N+vjClKd//KTTdfhF1M4XCuEM=", ext="Bazinga!", mac="07uWxZfesjgR9wGYXMfCPvocryS9ct8Ir6/83zj3A5s="
+
+> Hawk::Client.authenticate(
+>   %(Hawk hash="2QfCt3GuY9HQnHWyWD3wX68ZOKbynqlfYmuO2ZBRqtY=", mac="0ysNmHEhwCjww5yQdbVZ1yXQ58CiRkc8O3l+rSk/TZE="),
+>   :credentials => {
+>     :id => "123456",
+>     :key => "2983d45yun89q",
+>     :algorithm => "sha256"
+>   },
+>   :ts => 1365899773,
+>   :method => "POST",
+>   :path => "/somewhere/over/the/rainbow",
+>   :host => "example.net",
+>   :port => 80,
+>   :payload => "something to write about",
+>   :content_type => "text/plain",
+>   :nonce => "Ygvqdz",
+> )
+{ :id => "123456", :key => "2983d45yun89q", :algorithm => "sha256" }
+
+> Hawk::Client.calculate_time_offset(
+>   %(Hawk ts="1365741469", tsm="h/Ff6XI1euObD78ZNflapvLKXGuaw1RiLI4Q6Q5sAbM=", error="Some Error Message"),
+>   :credentials => { :id => "123456", :key => "2983d45yun89q", :algorithm => "sha256" }
+> )
+321
+
+> credentials = { :id => "123456", :key => "2983d45yun89q", :algorithm => "sha256" }
+{ :id => "123456", :key => "2983d45yun89q", :algorithm => "sha256" }
+> Hawk::Server.authenticate(
+>   %(Hawk id="123456", ts="1365900371", nonce="Ygvqdz", hash="9LxQVpfaAgyiyNeOgD8TEKP6RnM=", mac="lv54INsJZym8wnME0nQAu5jW6BA="),
+>   :method => "POST",
+>   :path => "/somewhere/over/the/rainbow",
+>   :host => "example.net",
+>   :port => 80,
+>   :content_type => "text/plain",
+>   :credentials_lookup => lambda { |id| id == credentials[:id] ? credentials : nil },
+>   :nonce_lookup => lambda { |nonce| },
+>   :payload => "something to write about"
+> )
+{ :id => "123456", :key => "2983d45yun89q", :algorithm => "sha256" }
+
+> res = Hawk::Server.authenticate(
+>   %(Hawk id="123456", ts="1365901299", mac="zTu3FSTmdsdSaLHd/DrpeQRkuYzcb0snYYKOmwDwP3w="),
+>   :method => "POST",
+>   :path => "/somewhere/over/the/rainbow",
+>   :host => "example.net",
+>   :port => 80,
+>   :content_type => "text/plain",
+>   :credentials_lookup => lambda { |id| id == credentials[:id] ? credentials : nil },
+>   :nonce_lookup => lambda { |nonce| }
+> )
+#<Hawk::AuthenticationFailure:0x007f95cba33168 @key=:nonce, @message="Missing nonce", @options={:credentials=>{:id=>"123456", :key=>"2983d45yun89q", :algorithm=>"sha256"}}>
+> res.header
+Hawk ts="1365901388", tsm="6mdH5DT66UeWlkBC9x2QD7Upt0eYnud9dB7y7xKoEoU=", error="Missing nonce"
+
+> Hawk::Server.build_authorization_header(
+>   :credentials => {
+>     :id => "123456",
+>     :key => "2983d45yun89q",
+>     :algorithm => "sha1"
+>   },
+>   :ts => 1365900682,
+>   :method => "POST",
+>   :path => "/somewhere/over/the/rainbow",
+>   :host => "example.net",
+>   :port => 80,
+>   :ext => "Bazinga!",
+>   :nonce => "Ygvqdz"
+> )
+Hawk ext="Bazinga!", mac="5D0CgZEXKEdeUFYbE5HQqb7ZooI="
+```
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,8 @@
-require "bundler/gem_tasks"
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+task :default => :spec

data/hawk-auth.gemspec

@@ -19,4 +19,6 @@ Gem::Specification.new do |gem|
 
   gem.add_development_dependency "bundler", "~> 1.3"
   gem.add_development_dependency "rake"
+  gem.add_development_dependency 'rspec', '~> 2.11'
+  gem.add_development_dependency 'mocha', '~> 0.13'
 end

data/lib/hawk.rb

@@ -1,6 +1,9 @@
 require 'hawk/version'
 
 module Hawk
-  NotImplementedError = Class.new(StandardError)
-  raise NotImplementedError.new("This implementation of hawk is currently empty!")
+  require 'hawk/crypto'
+  require 'hawk/authentication_failure'
+  require 'hawk/authorization_header'
+  require 'hawk/client'
+  require 'hawk/server'
 end

data/lib/hawk/authentication_failure.rb

@@ -0,0 +1,18 @@
+module Hawk
+  class AuthenticationFailure
+    attr_reader :key, :message
+    def initialize(key, message, options = {})
+      @key, @message, @options = key, message, options
+    end
+
+    def header
+      timestamp = Time.now.to_i
+      if @options[:credentials]
+        timestamp_mac = Crypto.ts_mac(:ts => timestamp, :credentials => @options[:credentials])
+        %(Hawk ts="#{timestamp}", tsm="#{timestamp_mac}", error="#{message}")
+      else
+        %(Hawk error="#{message}")
+      end
+    end
+  end
+end

data/lib/hawk/authorization_header.rb

@@ -0,0 +1,114 @@
+module Hawk
+  module AuthorizationHeader
+    extend self
+
+    REQUIRED_OPTIONS = [:method, :path, :host, :port].freeze
+    REQUIRED_CREDENTIAL_MEMBERS = [:id, :key, :algorithm].freeze
+    SUPPORTED_ALGORITHMS = ['sha256', 'sha1'].freeze
+    HEADER_PARTS = [:id, :ts, :nonce, :hash, :ext, :mac].freeze
+
+    MissingOptionError = Class.new(StandardError)
+    InvalidCredentialsError = Class.new(StandardError)
+    InvalidAlgorithmError = Class.new(StandardError)
+
+    def build(options, only=nil)
+      options[:ts] ||= Time.now.to_i
+      options[:nonce] ||= SecureRandom.hex(4)
+
+      REQUIRED_OPTIONS.each do |key|
+        unless options.has_key?(key)
+          raise MissingOptionError.new("#{key.inspect} is missing!")
+        end
+      end
+
+      credentials = options[:credentials]
+      REQUIRED_CREDENTIAL_MEMBERS.each do |key|
+        unless credentials.has_key?(key)
+          raise InvalidCredentialsError.new("#{key.inspect} is missing!")
+        end
+      end
+
+      unless SUPPORTED_ALGORITHMS.include?(credentials[:algorithm])
+        raise InvalidAlgorithmError.new("#{credentials[:algorithm].inspect} is not a supported algorithm! Use one of the following: #{SUPPORTED_ALGORITHMS.join(', ')}")
+      end
+
+      hash = Crypto.hash(options)
+      mac = Crypto.mac(options)
+
+      parts = {
+        :id => credentials[:id],
+        :ts => options[:ts],
+        :nonce => options[:nonce],
+        :mac => mac
+      }
+      parts[:hash] = hash if options.has_key?(:payload)
+      parts[:ext] = options[:ext] if options.has_key?(:ext)
+
+      "Hawk " << (only || HEADER_PARTS).inject([]) { |memo, key|
+        next memo unless parts.has_key?(key)
+        memo << %(#{key}="#{parts[key]}")
+        memo
+      }.join(', ')
+    end
+
+    def authenticate(header, options)
+      parts = parse(header)
+
+      now = Time.now.to_i
+
+      if options[:server_response]
+        credentials = options[:credentials]
+        parts.merge!(
+          :ts => options[:ts],
+          :nonce => options[:nonce]
+        )
+      else
+        unless options[:credentials_lookup].respond_to?(:call) && (credentials = options[:credentials_lookup].call(parts[:id]))
+          return AuthenticationFailure.new(:id, "Unidentified id")
+        end
+
+        if (now - parts[:ts].to_i > 1000) || (parts[:ts].to_i - now > 1000)
+          # Stale timestamp
+          return AuthenticationFailure.new(:ts, "Stale ts", :credentials => credentials)
+        end
+
+        unless parts[:nonce]
+          return AuthenticationFailure.new(:nonce, "Missing nonce")
+        end
+
+        if options[:nonce_lookup].respond_to?(:call) && options[:nonce_lookup].call(parts[:nonce])
+          # Replay
+          return AuthenticationFailure.new(:nonce, "Invalid nonce")
+        end
+      end
+
+      expected_mac = Crypto.mac(options.merge(
+        :credentials => credentials,
+        :ts => parts[:ts],
+        :nonce => parts[:nonce],
+        :ext => parts[:ext]
+      ))
+      unless expected_mac == parts[:mac]
+        return AuthenticationFailure.new(:mac, "Invalid mac")
+      end
+
+      expected_hash = parts[:hash] ? Crypto.hash(options.merge(:credentials => credentials)) : nil
+      if expected_hash && expected_hash != parts[:hash]
+        return AuthenticationFailure.new(:hash, "Invalid hash")
+      end
+
+      credentials
+    end
+
+    def parse(header)
+      parts = header.sub(/\AHawk\s+/, '').split(/,\s*/)
+      parts.inject(Hash.new) do |memo, part|
+        next memo unless part =~ %r{([a-z]+)=(['"])([^\2]+)\2}
+        key, val = $1, $3
+        memo[key.to_sym] = val
+        memo
+      end
+    end
+
+  end
+end

data/lib/hawk/client.rb

@@ -0,0 +1,22 @@
+require 'securerandom'
+
+module Hawk
+  module Client
+    extend self
+
+    def authenticate(authorization_header, options)
+      Hawk::AuthorizationHeader.authenticate(authorization_header, { :server_response => true }.merge(options))
+    end
+
+    def build_authorization_header(options)
+      Hawk::AuthorizationHeader.build(options)
+    end
+
+    def calculate_time_offset(authorization_header, options)
+      parts = AuthorizationHeader.parse(authorization_header)
+      expected_mac = Crypto.ts_mac(:ts => parts[:ts], :credentials => options[:credentials])
+      return unless expected_mac == parts[:tsm]
+      parts[:ts].to_i - Time.now.to_i
+    end
+  end
+end

data/lib/hawk/crypto.rb

@@ -0,0 +1,96 @@
+require 'base64'
+require 'openssl'
+
+##
+# Ruby 1.8.7 compatibility
+unless Base64.respond_to?(:strict_encode64)
+  Base64.class_eval do
+    def strict_encode64(bin)
+      [bin].pack("m0")
+    end
+  end
+end
+unless Base64.respond_to?(:urlsafe_encode64)
+  Base64.class_eval do
+    def urlsafe_encode64(bin)
+      strict_encode64(bin).tr("+/", "-_").gsub("\n", '')
+    end
+  end
+end
+
+module Hawk
+  module Crypto
+    extend self
+
+    def hash(options)
+      parts = []
+
+      parts << "hawk.1.payload"
+      parts << options[:content_type]
+      parts << options[:payload].to_s
+      parts << nil # trailing newline
+
+      Base64.encode64(OpenSSL::Digest.const_get(options[:credentials][:algorithm].upcase).digest(parts.join("\n"))).chomp
+    end
+
+    def normalized_string(options)
+      parts = []
+
+      parts << "hawk.1.#{options[:type] || 'header'}"
+      parts << options[:ts]
+      parts << options[:nonce]
+      parts << options[:method].to_s.upcase
+      parts << options[:path]
+      parts << options[:host]
+      parts << options[:port]
+      parts << options[:hash]
+      parts << options[:ext]
+      parts << nil # trailing newline
+
+      parts.join("\n")
+    end
+
+    def mac(options)
+      if !options[:hash] && options.has_key?(:payload)
+        options[:hash] = hash(options)
+      end
+
+      Base64.encode64(
+        OpenSSL::HMAC.digest(
+          openssl_digest(options[:credentials][:algorithm]).new,
+          options[:credentials][:key],
+          normalized_string(options)
+        )
+      ).chomp
+    end
+
+    def ts_mac(options)
+      Base64.encode64(
+        OpenSSL::HMAC.digest(
+          openssl_digest(options[:credentials][:algorithm]).new,
+          options[:credentials][:key],
+          "hawk.1.ts\n#{options[:ts]}\n"
+        )
+      ).chomp
+    end
+
+    def bewit(options)
+      options[:ts] ||= Time.now.to_i + options[:ttl].to_i
+
+      _mac = mac(options.merge(:type => 'bewit'))
+
+      parts = []
+
+      parts << options[:credentials][:id]
+      parts << options[:ts]
+      parts << _mac
+      parts << options[:ext]
+
+      Base64.urlsafe_encode64(parts.join("\\")).chomp.sub(/=+\Z/, '')
+    end
+
+    def openssl_digest(algorithm)
+      OpenSSL::Digest.const_get(algorithm.upcase)
+    end
+  end
+end