Authenticating REST Requests

The AudioMicro REST API used a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication formerly introduced by Amazon S3.

To authenticate a request, you first concatenate selected elements of the request to form a string. You then use your Secret Access Key to calculate the HMAC of that string. Informally, we call this process"signing the request," and we call the output of the HMAC algorithm the "signature" because it simulates the security properties of a real signature. Finally, you add this signature as a parameter of the request, using the syntax described in this section.

When the system receives an authenticated request, it fetches the Secret Access Key that you claim to have, and uses it in the same way to compute a "signature" for the message it received. It then compares the signature it calculated against the signature presented by the requester. If the two signatures match, then the system concludes that the requester must have access to the Secret Access Key, and therefore acts with the authority of the principal to whom the key was issued. If the two signatures do not match, the request is dropped and the system responds with an error message.

Example:

Authenticated Amazon S3 REST Request
GET /api/1.1/categories/browse/?CategoryID=2 HTTP/1.1
Host: api.audiomicro.com
Date: Mon, 27 Mar 2009 16:25:38 +0030
Authorization: AUDIOMICRO 0PN5X16HBGZHT7JJ3X82:SF7y/ZXX8aSX5KnRjKnuOlP7S2k=

The Authentication Header

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

Authorization: AUDIOMICRO AccessKeyId:Signature

Developers are issued an AudioMicro Access Key ID and AudioMicro Secret Access Key when they register. For request authentication, the AccessKeyId element identifies the secret key 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, then the requester will have demonstrated possession to the AudioMicro 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 pseudo-grammar that illustrates the construction of the Authorization request header (\n means the Unicode code point U+000A commonly called newline).

HMAC-SHA1 is an algorithm defined by RFC 2104 (go to RFC 2104 - Keyed-Hashing for Message Authentication ). The algorithm takes as input two byte-strings: a key and a message. For AudioMicro Request authentication, use your AudioMicro Secret Access Key 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.

Authentication Examples

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.

Example

GetObject

This example gets a categories list.

GET /api/1.1/categories/browse/?CategoryID=92
&PerPage=25
&Format=xml
HTTP/1.1
Host: api.audiomicro.com
Date: Wed, Apr 1 2009 18:00:19 +0030
Authorization: AUDIOMICRO 
0PN5X16HBGZHT7JJ3X82:SF7y/ZXX8aSX5KnRjKnuOlP7S2k=

"GET\n" + "\n"
Wed, Apr 1 2009 18:00:19 +0030\n. "\n"/api/1.1/categories/browse/?CategoryID=92

Query String Request Authentication Alternative

You can authenticate certain types of requests by passing the required information as query-string parameters instead of using the Authorization HTTP header. This is useful for enabling direct third-party browser access to your private AudioMicro data, without proxying the request. The idea is to construct a "pre-signed" request and encode it as a URL that an end-user's browser can retrieve. Additionally, you can limit a pre-signed request by specifying an expiration time.

Following is an example query string authenticated AudioMicro REST request.

GET /api/1.1/categories/browse/?CategoryID=1
&AccessKeyId=0PN5X16HBGZHT7JJ3X82
&Expires=1238598470
&Signature=SF7y/ZXX8aSX5KnRjKnuOlP7S2k= 
HTTP/1.1
Host: api.audiomicro.com
Date: Wed, Apr 1 2009 18:00:19 +0030

The query string request authentication method doesn't require any special HTTP headers. Instead, the required authentication elements are specified as query string parameters:

The query string request authentication method differs slightly from the ordinary method but only in the format of the Signature request parameter and the StringToSign element. Following is pseudo-grammar that illustrates the query string request authentication method.

Signature = URL-Encode( Base64( HMAC-SHA1( UTF-8-Encoding-Of( StringToSign ) ) ) );
StringToSign = HTTP-VERB + "\n" +
Content-MD5 + "\n" +
Content-Type + "\n" +
Expires + "\n" +
CanonicalizedResource;

Notice how the Signature is URL-Encoded to make it suitable for placement in the query-string.

This example gets a categories list.

GET /api/1.1/categories/browse/?CategoryID=2
&AccessKeyId=0PN5X16HBGZHT7JJ3X82
&Expires=1238598470
&Signature=SF7y/ZXX8aSX5KnRjKnuOlP7S2k=
HTTP/1.1
Host: api.audiomicro.com
Date: Wed, Apr 1 2009 18:00:19 +0030

"GET\n" + "\n" + "\n" +"1238598470\n" + 
"/api/1.1/categories/browse/?CategoryID=2"