SNS authentication scheme

Some SolarNetwork integrations use a custom authentication scheme adapted from the SNWS2 scheme. For example, the SolarNode STOMP server uses this scheme. Clients of the API must authenticate using a HMAC+SHA256 digest of specific request data.

💡 Note that within this document the terms request and header are abstract, because the underlying communication protocol is not protocol-specific. A request refers to a message sent by the client wishing to authenticate with a server, and header refers to named metadata included with that request.

Request date

The request must include a date header. This date is used in the signature message digest and the key used to sign the message so its value must be known by the client and communicated to the server.

The value of the request date must match the current date on server at the time the request is made, within a small tolerance value. If the difference between the header date and the server's system date is too large, an error will be generated and authentication will fail with a message along the lines of date skew too large.

Authorization

The request must include an authorization header using this syntax:

SNS Credential=principal,SignedHeaders=headerList,Signature=signature

where principal, headerList, and sig are placeholders for the authentication information, described in the following sections. The order of these comma-delimited elements does not matter. For example these two header values are effectively equivalent:

SNS Credential=bob@example.com,SignedHeaders=date,Signature=0123abc

SNS Signature=0123abc,Credential=bob@example.com,SignedHeaders=date

Authorization principal

The principal in the Credential=principal part of the authorization header is an identifier for the actor making the request, such as a username, email address, or token ID. For example:

Credential=bob@example.com

Authorization signed header list

The headerList in the SignedHeaders=headerList part of the authorization header is a semicolon-delimited list of header names included in the signature. For example:

SignedHeaders=date

Authorization signature

The signature in the Signature=signature part of the authorization header is a HMAC+SHA256 digest using a signing key derived from a secret value and signing message derived from the request details, encoded as a hexidecimal string.

An example authorization header using this scheme looks like this:

SNS Credential=bob@example.com,SignedHeaders=date,Signature=80644221408b05b684a15d95e0...

Terms

The following table describes some terms used throughout this document.

Term	Description
principal	An identifier for the actor making the request, such as a username, email address, or
token ID.
secret	A secret value known only to the actor making the request.
newline character \n	The newline character is the ASCII character 0x0A, or commonly \n in programming languages.
UriEncode()	An encoding function that accepts a UTF-8 string argument and returns a copy where all characters other than A-Z, a-z, 0-9, _, -, ~, and . are replaced by %X, where X is the upper case hexidecimal number of the character's code point (see RFC 3986). For example, UriEncode("Hello, world.") results in Hello%2C%20world. Note these rules are stricter than what JavaScript's encodeURIComponent() method performs. See the _encodeURIComponent() example JavaScript function that performs the required encoding.
Trim()	A function that accepts a string argument and returns a copy where all leading and trailing whitespace characters have been removed.
Hex()	A function that accepts an arbitrary array of bytes and returns an ASCII-encoded string where all bytes have been treated as unsigned values (0-255) and converted to lower case hexidecimal string values (00 - ff).
SHA256()	A SHA256 encoding function that accepts a string argument and produces a 32-byte SHA256 digest.
HMAC_SHA256()	A HMAC+SHA256 encoding function that accepts a secret key and message data as arguments, e.g. HMAC(key, message) and produces a 32-byte HMAC signed SHA256 digest.

Canonical request message

A set of 5 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:

Component	Description
Verb	The uppercase HTTP verb used in the request, for example GET or POST.
Path	A URL path, starting at /, for example /services/setup.
Canonical headers	This is a newline-delimited string of all headers and associated values used to sign the request. The header names that appear here must match the signed header names list described next. See Canonical headers for more information.
Signed header names	This is a semicolon-delimited string of all header names used to sign the request. The names must be in lowercase and sorted. The header names that appear here must match those that also appear in the canonical headers list described previously. See Signed header names for more information.
Body content SHA256 digest	This is a Hex(SHA256()) digest of the request body content. If no body content is included then the Hex(SHA256()) digest of an empty string must be used. For example a JSON body of {"m":{"foo":"BAR"}} would result in 3fb055786e256de47c267183d53d67337afe7aed40e200a7ad798a256688782b.

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

Verb + '\n'
CanonicalUri + '\n'
CanonicalHeaderList + '\n'
SignedHeaderNames + '\n'
BodyContentSHA256

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

GET
/some/service
host:example.com
date:Fri, 03 Mar 2017 04:36:28 GMT
host;date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Here's an example of a SEND request:

SEND
/some/service
content-type:application/json; charset=UTF-8
digest:SHA-256=P7BVeG4lbeR8JnGD1T1nM3r+eu1A4gCnrXmKJWaIeCs=
host:example.com
date:Fri, 03 Mar 2017 04:29:07 GMT
content-type;digest;host;x-sn-date
3fb055786e256de47c267183d53d67337afe7aed40e200a7ad798a256688782b

Canonical headers

The canonical headers string is formed via this algorithm:

1. Lowercase all 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:
   1. If this is not the first name, append \n to the result
   2. Append Trim(name), :, and Trim(value) to the result

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

host:example.com
date:Fri, 03 Mar 2017 04:00:23 GMT

Signed header names

The request must at a minimum sign the date header name.

The signed header names string is formed via this algorithm:

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

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

host;date

If the 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;date

Signing key

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

HMAC_SHA256(HMAC_SHA256("SNS"+secret, utcDate), "sns_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 secret does not have to be held in memory, just the derived signing key does.

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

HMAC_SHA256(HMAC_SHA256("SNSABC123", "20170101"), "sns_request")

which results in a hex-encoded key of:

0bd3a3bfa9bc1694bc471ab775f8511e2a55d393f3c80333c0fecc2a74c8858b

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

Signing message

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

1. The literal string SNS-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:

SNS-HMAC-SHA256
20170303T043628Z
8f732085380ed6dc18d8556a96c58c820b0148852a61b3c828cb9cfd233ae05f

Signature value

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.