Hash Authentication

This document describes a method of providing client applications the ability to authenticate to our APIs. These APIs are Web APIs; clients use simple HTTP requests and responses to send and receive data.

We use a shared secret and a derived hash value to authenticate the requests - to ensure at the API end that the requests are indeed coming from sunapsis. The shared secret will be a string known to both the client application and the API back end.

A simple API request URI for retrieving a class list might look like this:

GET /esapis/v1.0/classlist?term=2015SP&subject=8.011

To use the hash authentication scheme, the client would add three additional request parameters to the request:

• user (an IS&T-assigned username representing the client system)

• timestamp (the current date and time)

• derived hash token

The hash token is determined by concatenating parameter values (including the timestamp, but not including the user) being sent in the request with the shared secret string, and then running the resultant string through the SHA256 hashing algorithm. The resulting string will be added as the final parameter in the request; its parameter name will be “hash”.

For example, let’s say the shared secret is “September” and that the following data is being sent in the GET request:

Before sending the request, the client will add a timestamp to the data in the request, so now the request will be something like:

GET /esapis/v1.0/classlist?term=2015SP&subject=8.011&timestamp=20140715113137

Then (also before the request is sent) to derive the hash value, the client will:

a) concatenate the parameter values data (not the parameter names) with the shared secret, giving:

2015SP8.01120140715113137September

The order of the values in this string is important - the API will be expecting the values in a particular order, so we will need to agree on an order and make sure we always use the same order.

b) run this string through the SHA-256 hash algorithm to give:

275607e4db71e75ba9a3d5e091efaf0f5e550cbbcf0a8a3b4502a960bdcebc85

c) add this hash value as a request parameter

d) add the “user” parameter to the request, so the data finally sent in the request is:

GET /esapis/v1.0/classlist?term=2015SP&subject=8.011&timestamp=20140715113137&hash=275607e4db71e75ba9a3d5e091efaf0f5e550cbbcf0a8a3b4502a960bdcebc85&user=clientusername

When this request is received by the API backend, the API will use the same procedure to derive a SHA-256 hash value, using the data from the incoming request. If the API's derived hash matches the incoming hash, the request will be deemed to be valid. If not, the request will be rejected.

The timestamp will be used to expire requests. When the API receives a request, even if the hash algorithm passes the test described above, we will then check the timestamp - if the timestamp is older than some pre-agreed interval (say, 5 minutes) the request will be rejected.