Authentication

Authentication within Moxie API’s is done with HMAC. This means HTTP requests on these API’s must be made with specific headers. Before going into detail on how these requests can be build here is a brief glossary of terms used when discussing Authentication.

HMAC
keyed-Hash Message Authentication Code: a code generated by calculating a hashing function in combination with a secret key.
Canonical representation
What is being hashed. String representation of the request being made.
Shared secret
Generally a string issued by the service owner to grant access to an API. This is used as the hashing key by both parties to successfully authenticate the user. NEVER sent visibly over the wire.
API Key
Sent over the wire to identify a request with a particular user.

Step 1. Building the “Canonical Representation”

As described above the canonical representation is what is being hashed by our hashing function to generate the HMAC. Within Moxie the canonical representation of a HTTP request looks like this:

{method}
{url}
{headers}

All of the canonical representation is in lowercase.

Where method is the HTTP method being invoked for example get, post, put, delete. url is the absolute URL being requested. headers is the only tricky part. Some of the HTTP request headers are included in the canonical representation. For Moxie we require the Date header and a special header, the X-HMAC-Nonce (in the canonical representation both of these will be lowercase of course). They are included in the following format:

date:{date}
x-hmac-nonce:{nonce}

The values of these headers is the responsibility of the client making the request. However we recommend following the HTTP spec and include a Date in the standard format, such as “Wed, 15 Nov 2013 06:25:24 GMT”. Perhaps more important is the usage of a good Cryptographic Nonce. Good options for a nonce are pseudo-random numbers.

Here is a complete example of a “canonical representation”:

POST
http://localhost:5000/notifications/alert
date:Wed, 15 Nov 2013 06:25:24 GMT
x-hmac-nonce:29582

Attention

There is not a new line character “\n” after the headers.

Step 2. Generating the HMAC

As mentioned before HMAC requires the use of a hashing function. We use the SHA-1 hashing function.

This step depends on your toolset, find your preferable hmac function and call it with the SHA-1 algorithm and your shared secret as the hash key and the canonical representation built above as the message to be hashed. Here are a few possible ways to run this

Using whatever tools appropriate you need just the hexidemical representation of the digest.

Step 3. Making the request

Set the Authorization HTTP header on your request to the hexidecimal digest value from the previous step. Also set a custom X-Moxie-Key header to the value of your API key, this is used to identify your request. Your complete HTTP request should look similar to this:

POST /alert HTTP/1.1
Host: api.m.ox.ac.uk
X-Moxie-Key: d51459b5-d634-48f7-a77c-d87c77af37f1
X-HMAC-Nonce: 12642
Date: Fri, 10 Jan 2014 11:49:55 GMT
Authorization: ccd61eddf0c6be849b13e524c171e4c14a0d571f
Content-Type: application/json

Should your request fail and you receive a 401. There should be a WWW-Authenticate header which will provide a “reason” why your request failed. This also describes how to make requests on the API:

WWW-Authenticate: HMACDigest realm="HMACDigest Moxie", reason="missing header: HTTP_AUTHORIZATION", algorithm="HMAC-SHA-1",

So this request failed because they missed the Authorization header.