= What is Rack::SimpleAuth

Rack::SimpleAuth will contain different Authentication Class Middlewares

Until now only HMAC is implemented...

== Installation

Add this line to your application's Gemfile:

    $ gem 'rack-simple_auth'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install rack-simple_auth

== Gem Status

{<img src="https://travis-ci.org/Benny1992/rack-simple_auth.svg?branch=v1.0.0rc" alt="Build Status" />}[https://travis-ci.org/Benny1992/rack-simple_auth]
{<img src="https://coveralls.io/repos/Benny1992/rack-simple_auth/badge.png" alt="Code Coverage" />}[https://coveralls.io/r/Benny1992/rack-simple_auth]
{<img src="https://badge.fury.io/rb/rack-simple_auth.png" alt="Gem Version" />}[http://badge.fury.io/rb/rack-simple_auth]
{<img src="https://gemnasium.com/Benny1992/rack-simple_auth.png" alt="Dependency Status" />}[https://gemnasium.com/Benny1992/rack-simple_auth]
{<img src="https://www.codeship.io/projects/f2d9d790-b0fe-0131-3fd5-025f180094b5/status" alt="Build Status" />}[https://www.codeship.io/projects/f2d9d790-b0fe-0131-3fd5-025f180094b5/status]
{<img src="https://codeclimate.com/github/Benny1992/rack-simple_auth.png" />}[https://codeclimate.com/github/Benny1992/rack-simple_auth]

== Usage

=== HMAC

To use HMAC Authorization you have to use the Rack::SimpleAuth::HMAC::Middleware for your Rack App

Basic Usage:

    require 'rack/lobster'
    require 'rack/simple_auth'

    request_config = {
      'GET' => 'path',
      'POST' => 'params',
      'DELETE' => 'path',
      'PUT' => 'path',
      'PATCH' => 'path'
    }

    use Rack::SimpleAuth::HMAC::Middleware do |options|
      options.tolerance = 1500 # 1500ms -> 1.5s

      options.secret = 'test_secret'
      options.signature = 'test_signature'

      options.logpath = "#{File.expand_path('..', __FILE__)}/logs"
      options.request_config = request_config
    end

    run Rack::Lobster.new

In general each request has a message (which is encrypted) in following format:

    { 'method' => @request.request_method, 'date' => date, 'data' => request_data }.to_json

For example accessing +GET /test+ with this configuration represents following message

    { 'method' => 'GET', 'date' => 1398821451494, 'data' => '/test' }.to_json


With the tolerance there is an adjustable amount of messages wich are built (Rack::SimpleAuth::HMAC::Middleware#allowed_messages)

This means a request could have a certain latency (delay) and the request is still authorized


==== Secure your REST Api:

To secure your REST Api you have to send the HTTP_AUTHORIZATION Header with each request where the HMAC Middleware is used.

For example +POST /form+ with params +{ name => benny1992 }+ is secured the following way:

Uncrypted Message:

  { 'method' => 'POST', 'date' => timestamp +- tolerance, 'data' => { 'name' => 'benny1992' } }.to_json

Encryption Mechanism:

  OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), @config.secret, message(date, i))

where @config.secret represents your secret which was set in the middleware dsl block and message represents the uncrypted message
for the specific timestamp(date) and delay(i)

===== Therefore you need following encryption mechanism on the client side (pseudocode):

  encrypted_message = OpenSSL::HMAC.hexdigest(OpenSSL:Digest.new('sha256'), 'test_secret', message)

  HTTP_AUTHORIZATION = encrypted_message:'test_signature'

===== Time formats

The timestamp and tolerance are in millisecond format:

In Ruby land this means:

  (Time.now.to_f * 1000).to_i

For PHP you have to use +round()+ and +microtime()+ :

  round(microtime(true) * 1000)

===== General your timestamp should only contain 13 digits and NO floating part

==== Examples

Examples can be found in examples dir

== Contributing

1. Fork it ( http://github.com/benny1992/rack-simple_auth/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request