Authograph

Flexible HTTP request HMAC signing and validation utility.

Installation

Add this line to your application's Gemfile:

gem 'authograph'

And then execute:

$ bundle

Or install it yourself as:

$ gem install authograph

Usage

To sign a request just will first need to generate a new secret key

my_secret = SecureRandom.base64(64)

Now that you have a secret key, create a new instance of the signer

signer = Authograph.signer # initialize a time signer with default options

And the call sign passing the request you need to sign and the secret

signer.sign(my_request, my_secret) # this will add the X-Signature header to the request

Yo can later validate the request by using authentic?

signer.authentic?(my_request, my_secret) # this will check the signature and the date by default

Signer options

IMPORTANT Remember to always configure both the signer-signer and the validator-signer using the same paremeters.

The following parameters are available when calling Authograph.signer:

  • digest: which digest algorithm to use ('sha384' by default).
  • header: header key to store signature in ('X-Signature' by default).
  • sign_headers: array of additional headers to include in the signing process. ([] by default).
  • sign_date: whether to include and validate the date (true by default).
  • date_header: header key to store date in ('X-Date' by default).
  • date_max_skew: maximum difference (in secs) between request time and validaton ('600' by default).

Testing (only rspec)

Sometimes is useful to stub the signing process on tests.

Make sure to include the rspec extensions on your spec_helper.rb:

require 'authograph/rspec'

Now you can call the stub_authograph inside your tests:

before { stub_authograph(:any, 'mysignature') }
before { stub_authograph({ secret: 'my_secret' }, 'mysignature') } # only stub signatures for a given secret (TODO)
before { stub_authograph({ path: '/my/path' }, 'mysignature') } # only stub signatures for a given path (TODO)

Generated signature structure

The signature is generated by building a canonical payload with the following structure:

<request method (uppercase), ex: GET>
<request full path, ex: /some/path?sure>
<content type, ex: application/json>
<body md5 as base64>
<header #1 content>
<header #2 content>
...

And then applying the HMAC-SHA384 hashing function to it to get the signature. The signature is then written to the request header using the following format:

HMAC-SHA384 <base64(signature)>

When using date validation an additiona X-Date header is added to the request.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/SurBTC/authograph. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.