Page History

...

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 client applciation application "username", a shared secret and a derived hash value to authenticate the requests, to determine which client application is talking to our API. The shared secret will be a string known to both the client application and the API back end. Typically, IS&T determines the value of the secret and communicates the value to the client application developer through a secure channel: a phone conversation, perhaps.

...

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

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

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:

...

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

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.

...

import urllib2
import json
import hashlib
import datetime

# The base URL:
urlBase="https://esapis-test.mit.edu:8443/esapis/v1.0/classlist?term=2015SP&subject=8.011"

# For authentication, as well as the base query parameters (term and subject), 
# the URL must include these additional query parameters:
#    user, timestamp, hash
#
# Form the hash variable (SHA-256 hash of base parameter values + timestamp + shared secret).

user = "gravytrain"
secret = "September"

timeStamp = datetime.datetime.today().strftime('%Y%m%d%H%M%S')
toBeHashed = "2015SP" + "8.011" + timeStamp + secret
hashObj = hashlib.sha256(toBeHashed.encode())

# Complete the URL string by adding the additional parameters (timestamp, user, and hash):
url = urlBase + "&timestamp=" + timeStamp + "&user=" + user + "&hash=" + hashObj.hexdigest()

# Get the data from the API in JSON form.
result = json.load(urllib2.urlopen(url))

Some Other Languages/Environments

Other languages provide similar capability for generating SHA256 hash values. All the examples are generating hashes for a string with value "some value".

Java:

import java.security.MessageDigest;

...

        String textToBeHashed = "some value";
        MessageDigest digest = MessageDigest.getInstance(args[1]);
        byte[] hash = digest.digest(textToBeHashed.getBytes("UTF-8"));    
        StringBuffer hexString = new StringBuffer();
        for (int i = 0; i < hash.length; i++) {
            String hex = Integer.toHexString(0xff & hash[i]);
            if(hex.length() == 1) hexString.append('0');
            hexString.append(hex);
        }

Bash Shell Command Line:

echo -n "some value"|sha256sum

Javascript:

<script type="text/javascript" src="sjcl.min.js" ></script>

<script language="JavaScript" type="text/javascript">
	var bitArray = sjcl.hash.sha256.hash("some value");
	var hash = sjcl.codec.hex.fromBits(bitArray);
</script>