hmac_authentication 0.0.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6b70792ff95d35d009ad4508ad0a2f023ecad063
-  data.tar.gz: 72a5c827090f6b34193e06f27b8e220fa0df3c8b
+  metadata.gz: 93cb19ecbf56f6f4054b58899b122fd4dd6f0a28
+  data.tar.gz: 88e37b55037f15851158565db2fa11fc81175078
 SHA512:
-  metadata.gz: e979ffd7608fb388dff2512da040c43a3811cd28b948fa6bf9ce622e5740a18cea5b6ff490473553c6dc6356cb1f4db16cad8dfa6ac6beb8c30b570e75a57c1e
-  data.tar.gz: f93f9077f46ba1e8e22d89c6cbe286fd7a8d3eee40862565636189ec1cb084b454ea19853e8f10aba33d1c86d286530a962fd55545db2411d0ca3afb5d73c342
+  metadata.gz: d3ee6450b5e285164b17d74f1a54ee216e6a1dd0853cade9775951a0ec55ddd4df8b081be4ea734792ef4dbde526a25b120654787e658bf7e27394b2b3bca90d
+  data.tar.gz: 0d1aa098c990d41d42d9fcf93b96404700d02388cade6308c0a981504b30c51d87c3e037326b168c94f3ba2d58b1309de45caec4d1588993bafc854a7e601fa1

data/README.md

@@ -1,6 +1,19 @@
 # hmac_authentication RubyGem
 
-Signs and validates HTTP requests based on a shared-secret HMAC signature.
+Signs and authenticates HTTP requests based on a shared-secret HMAC signature.
+
+Developed in parallel with the following packages for other languages:
+- Go: [github.com/18F/hmacauth](https://github.com/18F/hmacauth/)
+- Node.js: [hmac-authentication](https://www.npmjs.com/package/hmac-authentication)
+
+**Warning: Repeated HTTP headers will cause an authentication failure!**
+Because of the way that Ruby's
+[Net::HTTPHeader.initialize_http_header](https://github.com/rubysl/rubysl-net-http/blob/2.0/lib/net/http/header.rb)
+method is implemented, it will discard all but the last of a series of
+repeated headers. The packages for other languages will combine repeated
+headers into one. Therefore, if your Ruby service receives an signed request
+from a server using one of these other modules, and the request has repeated
+headers, authentication of the request will fail.
 
 ## Installation
 
@@ -13,7 +26,7 @@ gem 'hmac_authentication'
 
 If you're not using Bundler, start.
 
-## Validating incoming requests
+## Authenticating incoming requests
 
 Inject something resembling the following code fragment into your request
 handling logic as the first thing that happens before the request body is
@@ -24,10 +37,15 @@ making the request:
 ```ruby
 require 'hmac_authentication'
 
-def my_handler(request, headers)
-  result, header_signature, computed_signature = (
-    HmacAuthentication.validate_request(request, headers, secret_key))
-  if result != HmacAuthentication::MATCH
+# When only used for authentication, it doesn't matter what the first argument
+# is, because the hash algorithm used for authentication will be parsed from
+# the incoming request signature header.
+auth = HmacAuthentication::HmacAuth.new(
+  'sha1', secret_key, signature_header, headers)
+
+def request_handler(request)
+  result, header_sig, computed_sig = auth.authenticate_request request
+  if result != HmacAuthentication::HmacAuth::MATCH
     # Cancel the request, optionally logging the values above.
   end
 end
@@ -35,8 +53,18 @@ end
 
 ## Signing outgoing requests
 
-Call `request_signature(request, headers, secretKey)` to sign a request before
-sending.
+Do something similar to the following.
+
+```ruby
+digest_name = 'sha1' # Or any other available Hash algorithm.
+auth = HmacAuthentication::HmacAuth.new(
+  digest_name, secret_key, signature_header, headers)
+
+def make_request(request)
+  // Prepare request...
+  auth.sign_request request
+end
+```
 
 ## Public domain
 

data/lib/hmac_authentication/signature.rb

@@ -1,4 +1,5 @@
 require 'base64'
+require 'fast_secure_compare/fast_secure_compare'
 require 'openssl'
 
 module HmacAuthentication
@@ -8,20 +9,74 @@ module HmacAuthentication
   MATCH = 4
   MISMATCH = 5
 
-  def self.signed_headers(request, headers)
-    headers.map { |name| request[name] || '' }
-  end
+  RESULT_CODE_STRINGS = %w(
+    NO_SIGNATURE
+    INVALID_FORMAT
+    UNSUPPORTED_ALGORITHM
+    MATCH
+    MISMATCH
+  )
 
-  def self.string_to_sign(req, headers)
-    # TODO(mbland): Test for paths of the form 'http://foo.com/bar?baz'
-    [req.method, signed_headers(req, headers).join("\n"), req.uri.path]
-      .join("\n")
+  def self.result_code_to_string(code)
+    index = code - 1
+    index >= 0 ? RESULT_CODE_STRINGS[index] : nil
   end
 
-  def self.request_signature(request, digest, headers, secret_key)
-    hmac = OpenSSL::HMAC.new secret_key, digest
-    hmac << string_to_sign(request, headers) << (request.body || '')
-    digest.name.downcase + ' ' + Base64.strict_encode64(hmac.digest)
+  class HmacAuth
+    attr_reader :digest, :secret_key, :signature_header, :headers
+
+    def initialize(digest_name, secret_key, signature_header, headers)
+      @digest = HmacAuthentication.parse_digest digest_name
+      if digest.nil?
+        fail "HMAC authentication digest is not supported: #{digest_name}"
+      end
+
+      @secret_key = secret_key
+      @signature_header = signature_header
+      @headers = headers
+    end
+
+    def string_to_sign(req)
+      [req.method,
+       signed_headers(req).join("\n"),
+       HmacAuthentication.hash_url(req)].join("\n") + "\n"
+    end
+
+    def sign_request(req)
+      req[signature_header] = request_signature req
+    end
+
+    def request_signature(request)
+      request_signature_impl request, digest
+    end
+
+    def signature_from_header(request)
+      request[signature_header]
+    end
+
+    def authenticate_request(request)
+      header = signature_from_header request
+      return NO_SIGNATURE unless header
+      components = header.split ' '
+      return INVALID_FORMAT, header unless components.size == 2
+      parsed_digest = HmacAuthentication.parse_digest components.first
+      return UNSUPPORTED_ALGORITHM, header unless parsed_digest
+      computed = request_signature_impl request, parsed_digest
+      [HmacAuthentication.compare_signatures(header, computed),
+       header, computed]
+    end
+
+    private
+
+    def signed_headers(request)
+      headers.map { |name| (request.get_fields(name) || []).join(',') }
+    end
+
+    def request_signature_impl(request, digest_)
+      hmac = OpenSSL::HMAC.new secret_key, digest_
+      hmac << string_to_sign(request) << (request.body || '')
+      digest_.name.downcase + ' ' + Base64.strict_encode64(hmac.digest)
+    end
   end
 
   def self.parse_digest(name)
@@ -30,14 +85,14 @@ module HmacAuthentication
     nil
   end
 
-  def self.validate_request(request, headers, secret_key)
-    header = request['Gap-Signature']
-    return NO_SIGNATURE unless header
-    components = header.split ' '
-    return INVALID_FORMAT, header unless components.size == 2
-    digest = parse_digest components.first
-    return UNSUPPORTED_ALGORITHM, header unless digest
-    computed = request_signature(request, digest, headers, secret_key)
-    [(header == computed) ? MATCH : MISMATCH, header, computed]
+  def self.compare_signatures(header, computed)
+    FastSecureCompare.compare(computed, header) ? MATCH : MISMATCH
+  end
+
+  def self.hash_url(req)
+    result = "#{req.uri.path}"
+    result << '?' << req.uri.query if req.uri.query
+    result << '#' << req.uri.fragment if req.uri.fragment
+    result
   end
 end

data/lib/hmac_authentication/version.rb

@@ -1,3 +1,3 @@
 module HmacAuthentication
-  VERSION = '0.0.0'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hmac_authentication
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Mike Bland
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-02 00:00:00.000000000 Z
+date: 2015-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: fast_secure_compare
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: go_script
   requirement: !ruby/object:Gem::Requirement