SolarNet API authentication scheme

SolarNet uses a custom HTTP authentication scheme roughly similar to the Amazon S3 web API scheme. Clients of the API must use a security token pair to authenticate each request using a HMAC+SHA1 digest of specific request headers.

Request date

The request must include a HTTP date header, either using the standard HTTP Date header or the custom X-SN-Date header. If X-SN-Date is provided, it will be used in preference to the Date header. The exact date included in HTTP header is included in the message digest so its value must be known by the client. As many browser AJAX fameworks set the Date header automatically, the X-SN-Date can be easier to use.

The value of the request date must match the current date on SolarNetwork at the time the request is made, within a small tolerance value. If the difference between the HTTP header date and the SolarNetwork system date is too large, a HTTP 401 error will be returned with a message along the lines of date skew too large.

Authorization

The request must include a standard HTTP Authorization header using SolarNetworkWS as the authorization scheme. The authorization value is in the form token:hash where token is a SolarUser generated authorization token and hash is the HMAC+SHA1 hash generated from the token secret and message content, encoded as a Base64 string.

Digest message content

Each request must generate a message out of details included with the request; that message is then used as the input to the HMAC+SHA1 digest algorithm used to authenticate the request. The message consists of the following items, delimited by a newline character such that the last item does not have a newline character added to it (newline character is 0x0A, or \n in most programming languages):

1. HTTP request method, e.g. GET
2. Value of Content-MD5 header (or empty string if none)
3. Value of Content-Type header (or empty string if no content)
4. Request date, from either a X-SN-Date header or a standard Date header, using the pattern EEE, dd MMM yyyy HH:mm:ss zzz in the GMT time zone (the zzz value must be the literal text GMT)
5. Request URI, including lexicographically sorted request parameters. The request parameters must be included regardless of the HTTP method if application/x-www-form-urlencoded encoding is used, for example, a POST request (see below).

Digest request URI

The request URI component of the message digest must contain the request parameters, sorted lexicographically. If the HTTP body is encoded as application/x-www-form-urlencoded, the parameters must be added to the URI as well. For example, imagine a HTTP request such as:

POST /solaruser/api/v1/sec/instr/add HTTP/1.1
Host: data.solarnetwork.net
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 100

nodeId=11&topic=SetControlParameter&parameters%5B0%5D.name=/power/switch/1&parameters%5B0%5D.value=1

For the message request URI, the POST parameters would be sorted into

1. nodeId=1
2. parameters[0].name=/power/switch/1
3. parameters[0].value=1
4. topic=SetControlParameter

and appended like it were a HTTP GET request, like this:

/solaruser/api/v1/sec/instr/add?nodeId=11&parameters[0].name=/power/switch/1&parameters[0].value=1&topic=SetControlParameter

Note the parameters are not URL encoded for the message URI!

Putting it all together

Here is an example of a GET request using the SolarNetworkWS authentication scheme:

GET /solaruser/api/v1/sec/instr/viewActive?nodeId=11 HTTP/1.1
Host: data.solarnetwork.net
X-SN-Date: Mon, 23 Sep 2013 03:39:39 GMT
Authorization: SolarNetworkWS a09sjds09wu9wjsd9uy2:IXeexIsjH7beMhxLPU1//1fM9FA=

The raw value of the message content is below (note how lines #2 and #3 are empty):

GET


Mon, 23 Sep 2013 03:39:39 GMT
/solaruser/api/v1/sec/instr/viewActive?nodeId=11

Assuming the message is stored in a variable msg then the Authorization header would be calculated like this, using pseudo code:

token = "a09sjds09wu9wjsd9uy2";          // the SolarNet auth token
secret = "my token secret";              // the secret associated with the SolarNet auth token
msg = "...";                             // calculated via rules above
hash = Base64(HmacSHA1(msg, secret));    // call function to hash message, then Base64 encode
authHeader = "Authorization: SolarNetworkWS " +token + ":" + hash;

API Sampler

See http://data.solarnetwork.net/dev/api/sample.html for a jQuery client implementation of the SolarNetworkWS authentication scheme designed to showcase how the API can be used.