HMAC Authentication

This module provides support for HMAC authentication, and it implements parts of RFC2104. The only hashing algorithm supported is HMAC SHA-256.

The secrets are stored on the server side in plain text. Please ensure that the configuration files have appropriate permissions.

Example configuration

The following configuration will allow the consumers with username:secret foo:key1 and bar:key2, access to example.com/ and paths below. A client/server clock skew of 300 seconds (+/-) is allowed. Multiple consumers can be added.

{
    "name": "example",
    "host": "example.com",
    "path": "/*",
    "modules": [
        {
            "order": 0,
            "name": "auth-hmac",
            "general": {
                "skew": 300
            },
            "consumers": {
                "foo": {
                    "secret": "key1"
                },
                "bar": {
                    "secret": "key2"
                }
            }
        }
    ]
}

Default configuration attributes

Attribute	Required	Type	Default	Description
`skew`	No	Int	300	The maximum clock skew allowed, specified in seconds.

Consumer configuration attributes

Attribute	Required	Type	Description
`secret`	Yes	String	The secret key for calculation and verification of the HMAC value.

Request headers

Header	Required	Type	Description
`X-HMAC`	Yes	String	The HMAC computed by the client using `HMAC-SHA256(host + path + timestamp)`.
`X-Timestamp`	Yes	Int	The current timestamp (UTC) in epoch format.

It is possible to specify these as query parameters instead of request headers. Query parameters are case sensitive and should be provided in lower case: x-hmac and x-timestamp. Request headers are case insensitive.

Response status

Status	Description
`200`	The request was authorized to access the specified resource.
`401`	Unauthorized.

Response headers

Header	Description
`X-Auth-Error`	Any human readable authentication error, if present.
`X-Auth-Type`	The auth type used, will with this module be `hmac`.
`X-Auth-User`	The username of the authorized user.
`X-Auth-Id`	The username of the authorized user.

Example client with cURL

#!/bin/bash

host="example.com"
path="/42"
secret="key1"

timestamp=$(date -u +%s)
hmac=$(echo -n "${host}${path}${timestamp}" | \
        openssl dgst -sha256 -binary -hmac "${secret}" | \
        base64)

curl -i http://localhost:8088${path} \
        -H "x-hmac: $hmac" \
        -H "x-timestamp: $timestamp" \
        -H "host: ${host}"