SolarNet uses a custom HTTP authentication scheme respectively adapted from the Amazon S3 web API V4 scheme. Clients of the API must use a security token pair to authenticate each request using a HMAC+SHA256 digest of specific request data.

The V1 version is still supported, but clients should migrate to this version.

See https://go.solarnetwork.net/dev/api/ for a JavaScript client implementation of this authentication scheme designed to showcase how the API can be used.

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 used in the signature message digest and the key used to sign the message 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.

The request must include a standard HTTP Authorization header using SNWS2 as the authorization scheme. The authorization value is in the form Credential=tokenId,SignedHeaders=headerList,Signature=hash where tokenId is a SolarUser generated authorization token, headerList is a semicolon-delimited list of HTTP headers included in the signature, and hash is the HMAC+SHA256 digest using a signing key derived from the token secret and signing message derived from the request details, encoded as a hexidecimal string.

An example Authorization HTTP header using this scheme looks like this:

Authorization: SNWS2 Credential=_tA{l51G2c08^icCXMyC,SignedHeaders=host;x-sn-date,Signature=854ed87aa277436d6771cd28fa4fb400ccccc7befe6cad8814b1f2e2bad66d32

The following table describes some terms used throughout this document.

A set of 6 items from the request is used to form a canonical request message string. The string is formed by concatenating the following items with the \n newline character:

To summarise more succinctly in pseudo code, the canonical request message is composed of lines like this:

HTTPVerb + '\n'
CanonicalUri + '\n'
CanonicalQueryParameters + '\n'
CanonicalHeaderList + '\n'
SignedHeaderNames + '\n'
BodyContentSHA256

For example, a GET request might result in a canonical request message like this:

GET
/solarquery/api/v1/sec/datum/meta/50
sourceId=Foo
host:data.solarnetwork.net
x-sn-date:Fri, 03 Mar 2017 04:36:28 GMT
host;x-sn-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Here's an example of a POST request:

POST
/solarquery/api/v1/sec/datum/meta/50
sourceId=Foo
content-type:application/json; charset=UTF-8
digest:SHA-256=P7BVeG4lbeR8JnGD1T1nM3r+eu1A4gCnrXmKJWaIeCs=
host:data.solarnetwork.net
x-sn-date:Fri, 03 Mar 2017 04:29:07 GMT
content-type;digest;host;x-sn-date
3fb055786e256de47c267183d53d67337afe7aed40e200a7ad798a256688782b

The canonical query parameters string is formed via the following algorithm. Keep in mind and any POST request with a Content-Type of application/x-www-form-urlencoded the body content is treated like query parameters.

1. Sort all query parameter keys
2. For each sorted key + associated value pair:
3. If this is not the first key, append & to the result
4. Append UriEncode(key), =, and UriEncode(value) to the result

For example, if a request URL includes query parameters like /solarquery/api/v1/sec/range/interval?nodeId=1&sourceId=/foo/bar then the canonical query parameters string is:

nodeId=1&sourceId=%2Ffoo%2Fbar

The canonical headers string is formed via this algorithm:

1. Lowercase all HTTP headers that will be included in the signature data
2. Sort the lowercase header names
3. For each sorted, lowercase header name and value pair:
4. If this is not the first name, append \n to the result
5. Append Trim(name), :, and Trim(value) to the result

For example, if a request includes a Host header value data.solarnetwork.net and a X-SN-Date header value Fri, 03 Mar 2017 04:00:23 GMT then the canonical headers string is:

host:data.solarnetwork.net
x-sn-date:Fri, 03 Mar 2017 04:00:23 GMT

The request must at a minimum sign the following HTTP header names:

1. Host
2. Date (unless X-SN-Date is provided)
3. Content-Type (if body content is included in the request)
4. Any header starting with X-SN-.

The signed header names string is formed via this algorithm:

1. Lowercase all HTTP headers that will be included in the signature data
2. Sort the lowercase header names
3. For each sorted, lowercase header name:
4. If this is not the first name, append ; to the result
5. Append Trim(name) to the result

For example, if the request includes the Host and X-SN-Date headers, the signed header names string is:

host;x-sn-date

If the HTTP request includes body content then a Digest or Content-MD5 header should be included. The RFC 5843 Digest header using the SHA-256 algorithm is preferred. Examples headers are Digest: SHA-256=P7BVeG4lbeR8JnGD1T1nM3r+eu1A4gCnrXmKJWaIeCs= and Content-MD5: /o1mwr8CitmYCfPTCeZp4A==.

Another example, for a request including body content and the additional Digest header, would result in a signed header names string of:

content-type;digest;host;x-sn-date

When running behind a proxy, the SolarNet server needs to know the original request's Host value. SolarNet expects the Host HTTP header value to be set to the original request host, not the proxied host. If the Host header value does not contain a port (i.e. the proxy server does not pass this), a X-Forwarded-Port header can be provided to pass the requesting port number. If X-Forwarded-Port is not provided, a X-Forwarded-Proto header can be provided; if that value is https then a port of 443 will be assumed.

For example, given the following request headers:

Host: data.solarnetwork.net
X-Forwarded-Proto: https

the canonical Host value will be treated as data.solarnetwork.net:443. Similarly, given the following request headers:

Host: data.solarnetwork.net
X-Forwarded-Port: 443

the canonical Host value will also be treated as data.solarnetwork.net:443.

Here is an example Nginx configuration snippet that sets these headers appropriately:

proxy_pass https://data.solarnetwork.net:443;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Port $server_port;

The SolarUser token secret is not used directly to sign the final HMAC message. Instead a 32-byte key derived from the SolarUser token secret value is used. The algorithm to derive this key is defined as:

HMAC_SHA256(HMAC_SHA256("SNWS2"+tokenSecret, utcDate), "snws2_request")

The utcDate value is the signing date formatted as YYYYMMDD. A signing key is valid for up to 7 days from the date it is signed. For some security-sensitive applications this can be useful so the actual token secret does not have to be held in memory, just the derived signing key does. The signing key can be refreshed before it expires, allowing long-running apps to work without needing to know the token secret. After the signing key expires, the token secret would then need to be used again to generate a new signing key.

For example, if the token secret is ABC123 and the UTC date is January 1, 2017, the result is derived like:

HMAC_SHA256(HMAC_SHA256("SNWS2ABC123", "20170101"), "snws2_request")

which results in a hex-encoded key of:

1f96b28b651285e49d06989aebaee169fa67a5f6a07fb72a8325fce83b425ad6

Note that when signing the message, use the actual output of the HMAC_SHA256() function, not the hex encoded version of it.

The final message to sign is 3 lines of data delimited by a newline character:

1. The literal string SNWS2-HMAC-SHA256
2. The request date, formatted as an UTC ISO8601 timestamp like YYYYMMDD'T'HHmmss'Z'
3. The Hex(SHA256(CanonicalRequestMessage)) where CanonicalRequestMessage is the canonical request message string as described in the previous section.

For example, the signing message for a request might look like:

SNWS2-HMAC-SHA256
20170303T043628Z
8f732085380ed6dc18d8556a96c58c820b0148852a61b3c828cb9cfd233ae05f

The final signature value is calculated as Hex(HMAC_SHA256(signingKey,signingMessage)), where signingKey is the signing key and signingMessage is the signing message as described previously.