api-auth 1.5.0 → 2.6.0

data/README.md

@@ -1,14 +1,13 @@
 # ApiAuth
 
-[![Build Status](https://travis-ci.org/mgomes/api_auth.png?branch=master)](https://travis-ci.org/mgomes/api_auth)
-
-## IMPORTANT: See [CHANGELOG.md](/CHANGELOG.md) for security update information
+[![Build Status](https://github.com/mgomes/api_auth/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/mgomes/api_auth/actions)
+[![Gem Version](https://badge.fury.io/rb/api-auth.svg)](https://badge.fury.io/rb/api-auth)
 
 Logins and passwords are for humans. Communication between applications need to
 be protected through different means.
 
 ApiAuth is a Ruby gem designed to be used both in your client and server
-HTTP-based applications. It implements the same authentication methods (HMAC-SHA1)
+HTTP-based applications. It implements the same authentication methods (HMAC-SHA2)
 used by Amazon Web Services.
 
 The gem will sign your requests on the client side and authenticate that
@@ -22,41 +21,62 @@ have to be written in the same language as the clients.
 ## How it works
 
 1. A canonical string is first created using your HTTP headers containing the
-content-type, content-MD5, request URI and the timestamp. If content-type or
-content-MD5 are not present, then a blank string is used in their place. If the
-timestamp isn't present, a valid HTTP date is automatically added to the
-request. The canonical string is computed as follows:
+`content-type`, `X-Authorization-Content-SHA256`, request path and the date/time stamp.
+If `content-type` or `X-Authorization-Content-SHA256` are not present, then a blank
+string is used in their place. If the timestamp isn't present, a valid HTTP date is
+automatically added to the request. The canonical string is computed as follows:
+
+```ruby
+canonical_string = "#{http method},#{content-type},#{X-Authorization-Content-SHA256},#{request URI},#{timestamp}"
+```
 
-    canonical_string = 'http method,content-type,content-MD5,request URI,timestamp'
+e.g.,
+
+```ruby
+canonical_string = 'POST,application/json,,request_path,Tue, 30 May 2017 03:51:43 GMT'
+```
 
 2. This string is then used to create the signature which is a Base64 encoded
 SHA1 HMAC, using the client's private secret key.
 
 3. This signature is then added as the `Authorization` HTTP header in the form:
 
-    Authorization = APIAuth 'client access id':'signature from step 2'
+```ruby
+Authorization = APIAuth "#{client access id}:#{signature from step 2}"
+```
+
+A cURL request would look like:
 
-5. On the server side, the SHA1 HMAC is computed in the same way using the
+```sh
+curl -X POST --header 'Content-Type: application/json' --header "Date: Tue, 30 May 2017 03:51:43 GMT" --header "Authorization: ${AUTHORIZATION}"  https://my-app.com/request_path`
+```
+
+5. On the server side, the SHA2 HMAC is computed in the same way using the
 request headers and the client's secret key, which is known to only
 the client and the server but can be looked up on the server using the client's
 access id that was attached in the header. The access id can be any integer or
 string that uniquely identifies the client. The signed request expires after 15
 minutes in order to avoid replay attacks.
 
-
 ## References
 
-* [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 (HMAC)](http://tools.ietf.org/html/rfc2104)
+* [Hash functions](https://en.wikipedia.org/wiki/Cryptographic_hash_function)
+* [SHA-2 Hash function](https://en.wikipedia.org/wiki/SHA-2)
+* [HMAC algorithm](https://en.wikipedia.org/wiki/HMAC)
+* [RFC 2104 (HMAC)](https://tools.ietf.org/html/rfc2104)
+
+## Requirement
+
+This gem require Ruby >= 2.6 and Rails >= 6.0 if you use rails.
 
 ## Install
 
 The gem doesn't have any dependencies outside of having a working OpenSSL
 configuration for your Ruby VM. To install:
 
-    [sudo] gem install api-auth
+```sh
+[sudo] gem install api-auth
+```
 
 Please note the dash in the name versus the underscore.
 
@@ -72,6 +92,8 @@ Here is the current list of supported request objects:
 * Curb (Curl::Easy)
 * RestClient
 * Faraday
+* HTTPI
+* HTTP
 
 ### HTTP Client Objects
 
@@ -79,26 +101,30 @@ Here's a sample implementation of signing a request created with RestClient.
 
 Assuming you have a client access id and secret as follows:
 
-``` ruby
-    @access_id = "1044"
-    @secret_key = ApiAuth.generate_secret_key
+```ruby
+@access_id = "1044"
+@secret_key = ApiAuth.generate_secret_key
 ```
 
 A typical RestClient PUT request may look like:
 
-``` ruby
-    headers = { 'Content-MD5' => "e59ff97941044f85df5297e1c302d260",
-        'Content-Type' => "text/plain",
-        'Date' => "Mon, 23 Jan 1984 03:29:56 GMT" }
-    @request = RestClient::Request.new(:url => "/resource.xml?foo=bar&bar=foo",
-        :headers => headers,
-        :method => :put)
+```ruby
+headers = { 'X-Authorization-Content-SHA256' => "dWiCWEMZWMxeKM8W8Yuh/TbI29Hw5xUSXZWXEJv63+Y=",
+  'Content-Type' => "text/plain",
+  'Date' => "Mon, 23 Jan 1984 03:29:56 GMT"
+}
+
+@request = RestClient::Request.new(
+    url: "/resource.xml?foo=bar&bar=foo",
+    headers: headers,
+    method: :put
+)
 ```
 
 To sign that request, simply call the `sign!` method as follows:
 
-``` ruby
-    @signed_request = ApiAuth.sign!(@request, @access_id, @secret_key)
+```ruby
+@signed_request = ApiAuth.sign!(@request, @access_id, @secret_key)
 ```
 
 The proper `Authorization` request header has now been added to that request
@@ -111,8 +137,27 @@ If you are signing a request for a driver that doesn't support automatic http
 method detection (like Curb or httpi), you can pass the http method as an option
 into the sign! method like so:
 
-``` ruby
-    @signed_request = ApiAuth.sign!(@request, @access_id, @secret_key, :override_http_method => "PUT")
+```ruby
+@signed_request = ApiAuth.sign!(@request, @access_id, @secret_key, :override_http_method => "PUT")
+```
+
+If you want to use another digest existing in `OpenSSL::Digest`,
+you can pass the http method as an option into the sign! method like so:
+
+```ruby
+@signed_request = ApiAuth.sign!(@request, @access_id, @secret_key, :digest => 'sha256')
+```
+
+With the `digest` option, the `Authorization` header will be change from:
+
+```sh
+Authorization = APIAuth 'client access id':'signature'
+```
+
+to:
+
+```sh
+Authorization = APIAuth-HMAC-DIGEST_NAME 'client access id':'signature'
 ```
 
 ### ActiveResource Clients
@@ -120,23 +165,36 @@ into the sign! method like so:
 ApiAuth can transparently protect your ActiveResource communications with a
 single configuration line:
 
-``` ruby
-    class MyResource < ActiveResource::Base
-      with_api_auth(access_id, secret_key)
-    end
+```ruby
+class MyResource < ActiveResource::Base
+  with_api_auth(access_id, secret_key)
+end
 ```
 
 This will automatically sign all outgoing ActiveResource requests from your app.
 
-### Active Rest Client
+### Flexirest
 
-ApiAuth also works with [ActiveRestClient](https://github.com/whichdigital/active-rest-client) in a very similar way.
-Simply add this configuration to your ActiveRestClient initializer in your app and it will automatically sign all outgoing requests.
+ApiAuth also works with [Flexirest](https://github.com/andyjeffries/flexirest) (used to be ActiveRestClient, but that is now unsupported) in a very similar way.
+Simply add this configuration to your Flexirest initializer in your app and it will automatically sign all outgoing requests.
 
-``` ruby
-ActiveRestClient::Base.api_auth_credentials(@access_id, @secret_key)
+```ruby
+Flexirest::Base.api_auth_credentials(@access_id, @secret_key)
 ```
 
+### Faraday
+
+ApiAuth provides a middleware for adding authentication to a Faraday connection:
+
+```ruby
+require 'faraday/api_auth'
+Faraday.new do |f|
+  f.request :api_auth, @access_id, @secret_key
+end
+```
+
+The order of middlewares is important. You should make sure api_auth is last.
+
 ## Server
 
 ApiAuth provides some built in methods to help you generate API keys for your
@@ -144,23 +202,57 @@ clients as well as verifying incoming API requests.
 
 To generate a Base64 encoded API key for a client:
 
-``` ruby
-    ApiAuth.generate_secret_key
+```ruby
+ApiAuth.generate_secret_key
 ```
 
 To validate whether or not a request is authentic:
 
+```ruby
+ApiAuth.authentic?(signed_request, secret_key)
+```
+
+The `authentic?` method uses the digest specified in the `Authorization` header.
+For example SHA256 for:
+
+```sh
+Authorization = APIAuth-HMAC-SHA256 'client access id':'signature'
+```
+
+And by default SHA1 if the HMAC-DIGEST is not specified.
+
+If you want to force the usage of another digest method, you should pass it as an option parameter:
+
+```ruby
+ApiAuth.authentic?(signed_request, secret_key, :digest => 'sha256')
+```
+
+For security, requests dated older or newer than a certain timespan are considered inauthentic.
+
+This prevents old requests from being reused in replay attacks, and also ensures requests
+can't be dated into the far future.
+
+The default span is 15 minutes, but you can override this:
+
+```ruby
+ApiAuth.authentic?(signed_request, secret_key, :clock_skew => 60) # or 1.minute in ActiveSupport
+```
+
+If you want to sign custom headers, you can pass them as an array of strings in the options like so:
+
 ``` ruby
-    ApiAuth.authentic?(signed_request, secret_key)
+ApiAuth.authentic?(signed_request, secret_key, headers_to_sign: %w[HTTP_HEADER_NAME])
 ```
 
+With the specified headers values being at the end of the canonical string in the same order.
+
 If your server is a Rails app, the signed request will be the `request` object.
 
 In order to obtain the secret key for the client, you first need to look up the
 client's access_id. ApiAuth can pull that from the request headers for you:
 
 ``` ruby
-    ApiAuth.access_id(signed_request)
+ApiAuth.access_id(signed_request)
 ```
 
 Once you've looked up the client's record via the access id, you can then verify
@@ -172,12 +264,12 @@ Here's a sample method that can be used in a `before_action` if your server is a
 Rails app:
 
 ``` ruby
-    before_action :api_authenticate
+before_action :api_authenticate
 
-    def api_authenticate
-      @current_account = Account.find_by_access_id(ApiAuth.access_id(request))
-      head(:unauthorized) unless @current_account && ApiAuth.authentic?(request, @current_account.secret_key)
-    end
+def api_authenticate
+  @current_account = Account.find_by_access_id(ApiAuth.access_id(request))
+  head(:unauthorized) unless @current_account && ApiAuth.authentic?(request, @current_account.secret_key)
+end
 ```
 
 ## Development
@@ -188,7 +280,17 @@ take care of all that for you.
 
 To run the tests:
 
-    rake spec
+Install the dependencies for a particular Rails version by specifying a gemfile in `gemfiles` directory:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/rails_5.gemfile bundle install
+```
+
+Run the tests with those dependencies:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/rails_5.gemfile bundle exec rake
+```
 
 If you'd like to add support for additional HTTP clients, check out the already
 implemented drivers in `lib/api_auth/request_drivers` for reference. All of
@@ -196,8 +298,9 @@ the public methods for each driver are required to be implemented by your driver
 
 ## Authors
 
-* [Mauricio Gomes](http://github.com/mgomes)
-* [Kevin Glowacz](http://github.com/kjg)
+* [Mauricio Gomes](https://github.com/mgomes)
+* [Kevin Glowacz](https://github.com/kjg)
+* [Florian Wininger](https://github.com/fwininger)
 
 ## Copyright
 

data/Rakefile

@@ -10,4 +10,4 @@ RSpec::Core::RakeTask.new(:spec) do |spec|
   spec.pattern = FileList['spec/**/*_spec.rb']
 end
 
-task :default => :spec
+task default: :spec

data/VERSION

@@ -1 +1 @@
-1.5.0
+2.6.0

data/api_auth.gemspec

@@ -1,30 +1,42 @@
-# -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
+$LOAD_PATH.push File.expand_path('lib', __dir__)
 
 Gem::Specification.new do |s|
-  s.name = %q{api-auth}
-  s.summary = %q{Simple HMAC authentication for your APIs}
-  s.description = %q{Full HMAC auth implementation for use in your gems and Rails apps.}
-  s.homepage = %q{https://github.com/mgomes/api_auth}
+  s.name = 'api-auth'
+  s.summary = 'Simple HMAC authentication for your APIs'
+  s.description = 'Full HMAC auth implementation for use in your gems and Rails apps.'
+  s.homepage = 'https://github.com/mgomes/api_auth'
   s.version = File.read(File.join(File.dirname(__FILE__), 'VERSION'))
-  s.authors = ["Mauricio Gomes"]
-  s.email = "mauricio@edge14.com"
+  s.authors = ['Mauricio Gomes']
+  s.email = 'mauricio@edge14.com'
+  s.license = 'MIT'
 
-  s.add_development_dependency "appraisal"
-  s.add_development_dependency "rake"
-  s.add_development_dependency "amatch"
-  s.add_development_dependency "rspec", "~> 3.4"
-  s.add_development_dependency "actionpack", "< 5.0", "> 2.3.2"
-  s.add_development_dependency "activesupport", "< 5.0", "> 2.3.2"
-  s.add_development_dependency "activeresource", "~> 4.0"
-  s.add_development_dependency "rest-client", "~> 1.6.0"
-  s.add_development_dependency "curb", "~> 0.8.1"
-  s.add_development_dependency "httpi"
-  s.add_development_dependency "faraday"
-  s.add_development_dependency "multipart-post", "~> 2.0"
+  s.metadata = {
+    'rubygems_mfa_required' => 'true'
+  }
+
+  s.required_ruby_version = '>= 2.6.0'
+
+  s.add_development_dependency 'actionpack', '>= 6.0'
+  s.add_development_dependency 'activeresource', '>= 4.0'
+  s.add_development_dependency 'activesupport', '>= 6.0'
+  s.add_development_dependency 'amatch'
+  s.add_development_dependency 'appraisal'
+  s.add_development_dependency 'curb', '~> 1.0'
+  # DRb is required for Ruby 3.4+ but must avoid 2.0.6 which breaks Ruby 2.6
+  s.add_development_dependency 'drb', '>= 2.0.4', '< 2.0.6'
+  s.add_development_dependency 'faraday', '>= 1.1.0'
+  s.add_development_dependency 'grape', '~> 2.0'
+  s.add_development_dependency 'http'
+  s.add_development_dependency 'httpi'
+  s.add_development_dependency 'multipart-post', '~> 2.0'
+  s.add_development_dependency 'pry'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rest-client', '~> 2.0'
+  s.add_development_dependency 'rexml'
+  s.add_development_dependency 'rspec', '~> 3.4'
+  s.add_development_dependency 'rubocop', '~> 1.50'
 
   s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ["lib"]
+  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.require_paths = ['lib']
 end

data/gemfiles/rails_60.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "actionpack", "~> 6.0"
+gem "activeresource", "~> 5.1"
+gem "activesupport", "~> 6.0"
+
+gemspec path: "../"

data/gemfiles/rails_61.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "actionpack", "~> 6.1"
+gem "activeresource", "~> 5.1"
+gem "activesupport", "~> 6.1"
+
+gemspec path: "../"

data/gemfiles/rails_70.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "actionpack", "~> 7.0"
+gem "activeresource", "~> 6.0"
+gem "activesupport", "~> 7.0"
+
+gemspec path: "../"

data/lib/api-auth.rb

@@ -1,2 +1,2 @@
 # So you can require "api-auth" instead of "api_auth"
-require "api_auth"
+require 'api_auth'

data/lib/api_auth/base.rb

@@ -1,4 +1,3 @@
-# encoding: UTF-8
 # api-auth is a Ruby gem designed to be used both in your client and server
 # HTTP-based applications. It implements the same authentication methods (HMAC)
 # used by Amazon Web Services.
@@ -8,9 +7,7 @@
 # Rails ActiveResource, it will integrate with that. It will even generate the
 # secret keys necessary for your clients to sign their requests.
 module ApiAuth
-
   class << self
-
     include Helpers
 
     # Signs an HTTP request using the client's access id and secret key.
@@ -23,9 +20,9 @@ module ApiAuth
     #
     # secret_key: assigned secret key that is known to both parties
     def sign!(request, access_id, secret_key, options = {})
-      options = { :override_http_method => nil, :with_http_method => false }.merge(options)
+      options = { override_http_method: nil, digest: 'sha1' }.merge(options)
       headers = Headers.new(request)
-      headers.calculate_md5
+      headers.calculate_hash
       headers.set_date
       headers.sign_header auth_header(headers, access_id, secret_key, options)
     end
@@ -34,14 +31,19 @@ module ApiAuth
     # secret key. Returns true if the request is authentic and false otherwise.
     def authentic?(request, secret_key, options = {})
       return false if secret_key.nil?
-      options = { :override_http_method => nil }.merge(options)
 
-      headers = Headers.new(request)
-      if headers.md5_mismatch?
+      options = { override_http_method: nil, authorize_md5: false }.merge(options)
+
+      headers = Headers.new(request, authorize_md5: options[:authorize_md5])
+
+      # 900 seconds is 15 minutes
+      clock_skew = options.fetch(:clock_skew, 900)
+
+      if headers.content_hash_mismatch?
         false
       elsif !signatures_match?(headers, secret_key, options)
         false
-      elsif request_too_old?(headers)
+      elsif !request_within_time_window?(headers, clock_skew)
         false
       else
         true
@@ -52,7 +54,7 @@ module ApiAuth
     def access_id(request)
       headers = Headers.new(request)
       if match_data = parse_auth_header(headers.authorization_header)
-        return match_data[1]
+        return match_data[2]
       end
 
       nil
@@ -67,50 +69,54 @@ module ApiAuth
       b64_encode(Digest::SHA2.new(512).digest(random_bytes))
     end
 
-  private
+    private
 
-    AUTH_HEADER_PATTERN = /APIAuth ([^:]+):(.+)$/
+    AUTH_HEADER_PATTERN = /APIAuth(?:-HMAC-(MD5|SHA(?:1|224|256|384|512)?))? ([^:]+):(.+)$/.freeze
 
-    def request_too_old?(headers)
-      # 900 seconds is 15 minutes
-      begin
-        Time.httpdate(headers.timestamp).utc < (Time.now.utc - 900)
-      rescue ArgumentError
-        true
-      end
+    def request_within_time_window?(headers, clock_skew)
+      Time.httpdate(headers.timestamp).utc > (Time.now.utc - clock_skew) &&
+        Time.httpdate(headers.timestamp).utc < (Time.now.utc + clock_skew)
+    rescue ArgumentError
+      false
     end
 
     def signatures_match?(headers, secret_key, options)
       match_data = parse_auth_header(headers.authorization_header)
       return false unless match_data
 
-      options = options.merge(:with_http_method => true)
+      digest = match_data[1].nil? ? 'SHA1' : match_data[1].upcase
+      raise InvalidRequestDigest if !options[:digest].nil? && !options[:digest].casecmp(digest).zero?
+
+      options = { digest: digest }.merge(options)
 
-      header_sig = match_data[2]
-      calculated_sig_no_http = hmac_signature(headers, secret_key, {})
-      calculated_sig_with_http = hmac_signature(headers, secret_key, options)
+      header_sig = match_data[3]
+      calculated_sig = hmac_signature(headers, secret_key, options)
 
-      header_sig == calculated_sig_with_http || header_sig == calculated_sig_no_http
+      secure_equals?(header_sig, calculated_sig, secret_key)
     end
 
-    def hmac_signature(headers, secret_key, options)
-      if options[:with_http_method]
-        canonical_string = headers.canonical_string_with_http_method(options[:override_http_method])
-      else
-        canonical_string = headers.canonical_string
-      end
+    def secure_equals?(m1, m2, key)
+      sha1_hmac(key, m1) == sha1_hmac(key, m2)
+    end
+
+    def sha1_hmac(key, message)
       digest = OpenSSL::Digest.new('sha1')
+      OpenSSL::HMAC.digest(digest, key, message)
+    end
+
+    def hmac_signature(headers, secret_key, options)
+      canonical_string = headers.canonical_string(options[:override_http_method], options[:headers_to_sign])
+      digest = OpenSSL::Digest.new(options[:digest])
       b64_encode(OpenSSL::HMAC.digest(digest, secret_key, canonical_string))
     end
 
     def auth_header(headers, access_id, secret_key, options)
-      "APIAuth #{access_id}:#{hmac_signature(headers, secret_key, options)}"
+      hmac_string = "-HMAC-#{options[:digest].upcase}" unless options[:digest] == 'sha1'
+      "APIAuth#{hmac_string} #{access_id}:#{hmac_signature(headers, secret_key, options)}"
     end
 
     def parse_auth_header(auth_header)
       AUTH_HEADER_PATTERN.match(auth_header)
     end
-
-  end # class methods
-
-end # ApiAuth
+  end
+end

data/lib/api_auth/errors.rb

@@ -1,9 +1,10 @@
 module ApiAuth
-  
   # :nodoc:
   class ApiAuthError < StandardError; end
-  
+
   # Raised when the HTTP request object passed is not supported
   class UnknownHTTPRequest < ApiAuthError; end
-  
+
+  # Raised when the client request digest is not the same as the server
+  class InvalidRequestDigest < ApiAuthError; end
 end