Signing and Authenticating REST Requests

The Norsk API uses the standard HTTP Authorization header to pass authentication information. (The name of the standard header is unfortunate because it carries authentication information, not authorization.) Under the authentication scheme, the Authorization header has the following form:

Authorization: NorskAccessKeyId:Signature

Developers are issued a access key ID and secret access key when they register. For request authentication, the NorskAccessKeyId element identifies the access key ID that was used to compute the signature and, indirectly, the developer making the request.

The Signature element is the RFC 2104 HMAC-SHA1 of selected elements from the request, and so the Signature part of the Authorization header will vary from request to request. If the request signature calculated by the system matches the Signature included with the request, the requester will have demonstrated possession of the AWS secret access key. The request will then be processed under the identity, and with the authority, of the developer to whom the key was issued.

Following is pseudogrammar that illustrates the construction of the Authorization request header. (In the example, \n means the Unicode code point U+000A, commonly called newline).

Authorization = NorskAccessKeyId + ":" + Signature;
Signature = Base64( HMAC-SHA1( YourSecretAccessKeyID, UTF-8-Encoding-Of( StringToSign ) ) );
StringToSign = HTTP-Verb + "\n" +
    ToLowerCase(Content-MD5) + "\n" +
    Content-Type + "\n" +
    Date + "\n" +
    HTTP-Resource;

HMAC-SHA1 is an algorithm defined by RFC 2104 - Keyed-Hashing for Message Authentication . The algorithm takes as input two byte-strings, a key and a message. For Norsk request authentication, use your secret access key (YourSecretAccessKeyID) as the key, and the UTF-8 encoding of the StringToSign as the message. The output of HMAC-SHA1 is also a byte string, called the digest. The Signature request parameter is constructed by Base64 encoding this digest.

A valid time stamp (using either the HTTP Date header or an x-date alternative) is mandatory for authenticated requests. Furthermore, the client timestamp included with an authenticated request must be within 30 minutes of the Norsk system time when the request is received. If not, the request will fail with the RequestTimeTooSkewed error code. The intention of these restrictions is to limit the possibility that intercepted requests could be replayed by an adversary. For stronger protection against eavesdropping, use the HTTPS transport for authenticated requests.

Some HTTP client libraries do not expose the ability to set the Date header for a request. If you have trouble including the value of the 'Date' header in the canonicalized headers, you can set the timestamp for the request by using an 'x-date' header instead. The value of the x-date header must be in one of the RFC 2616 formats (http://www.ietf.org/rfc/rfc2616.txt). When an x-date header is present in a request, the system will ignore any Date header when computing the request signature. Therefore, if you include the x-date header, use the empty string for the Date when constructing the StringToSign. See the next section for an example.

The examples in this section use the (non-working) credentials in the following table.

In the example StringToSigns, formatting is not significant, and \n means the Unicode code point U+000A, commonly called newline. Also, the examples use "+0000" to designate the time zone. You can use "GMT" to designate timezone instead, but the signatures shown in the examples will be different.

GET /shipment/123/label HTTP/1.1
Date: Tue, 27 Mar 2007 19:36:42 +0000
Authorization: MISCACCEXAMPLE:vHhzsjuRLTLTAamvWFsSeI9Mltc=

GET\n
\n
\n
Tue, 27 Mar 2007 19:36:42 +0000\n
/shipment/123/label