Signing an Ooyala API query with AS3

In order to invoke Ooyala’s APIs we require that you sign each request using a combination of private keys, the request parameters, and an expiration time. The appended signature is generated with a SHA256 hash and then by creating a Base64 encoded

string of the SHA256 digest. There are a few smaller steps outlined in our documentation such as limiting the signature to 43 characters in length, removing any trailing equals signs, and URI encoding the signature to make sure it is URL friendly.

The AS3CoreLib (available over at Mike Chambers github) contains a crypto package, and particularly a SHA256 class. It also has a hashToBase64 method, even better! But… the Base64 utility class it uses no longer exists in the Flash runtime. The class mx.utils.Base64Encoder needs to be replaced for our use case, and you can find many online. The Base64 class I’ve chosen is freely available for use and modification from Jean-Philippe Auclair. Check out his blog post for a Base64 optimized AS3 lib.

Download my complete source code, or if you want to create your own, the following are the steps I’ve taken to modify the Adobe SHA256 class with a different Base64 utility.

Firstly, edit the SHA256 class in com.adobe.crypto and change the hashToBase64() function to look like this -

public static function hashToBase64( s:String ):String
{
  var blocks:Array = createBlocksFromString( s );
  var byteArray:ByteArray = hashBlocks(blocks);
 
  // use the new Base64 class			
  return Base64.encode(byteArray);
}

Next you need to generate the signature and create the URL for the request following Ooyala’s guidelines for signature generation.

public static function generateURL(pcode:String, scode:String,
                                   requestType:String, params:Array):String
{
  if (!params["expires"])
  {
    // if no expiry time exists, add one
	params["expires"] = new Date().time + 900; 
  }
 
  var stringToSign:String = scode;
  var url:String = "http://api.ooyala.com/" + requestType;
 
  url += "?pcode=" + pcode;
 
  var keys:Array = extractKeysAndSort(params);
 
  for each (var key:String in keys)
  {
	stringToSign += key + "=" + params[key];
	url += "&" + key + "=" + encodeURIComponent(params[key]);
  }
 
  var signature:String = SHA256.hashToBase64(stringToSign);
  signature = signature.replace(/=+$/, "");
  url += "&signature=" + encodeURIComponent(signature);
 
  return url;
}

And using the class is fairly simple. Remember to get your Partner Code and Secret Code from the developers tab in Backlot, then follow the API requirements for the specific call you want to make.

In this example I’m querying the Backlot API to return details of a video. The result of a query is an XML document that could include a paginated list of results for the query items.

First, set up your query parameters. If you don’t include an expiration time for the query, the utility class will add one for you.

// query parameters
var params:Array = [];
params["embedCode"] = "<INSERT VIDEO EMBEDCODE>";

Next, set your query type. This is the user-friendly RESTful URL structure that is appended to the API call, such as partner/query or partner/labels.

// query type
var queryType:String = "partner/query";

And finally, using your Partner code and Secret for your Backlot account, invoke the Ooyala API Utility in one of two ways, either return a URLRequest object, or a URL string.

// generate URL Request
var urlRequest:URLRequest = OoyalaAPIUtil.generateSignedURLRequest(
                                              pcode, scode, queryType, params);
 
var url:String = OoyalaAPIUtil.generateURL(pcode, scode, queryType, params);

The resulting XML from making the call will look something like this -

<?xml version="1.0" encoding="UTF-8"?>
<list totalResults="1" size="1" pageID="0" statistics-as-of_text="Tue Jul 19 00:40:01 UTC 2011" limit="500" statistics-as-of="1311036001">
  <item>
    <embedCode>12345678901234567890</embedCode>
    <title>Big Buck Bunny</title>
    <description>The Peach open movie project</description>
    <status>live</status>
    <content_type>Video</content_type>
    <uploadedAt>1297678678</uploadedAt>
    <length>596458</length>
    <size>928670754</size>
    <updatedAt>1304451370</updatedAt>
    <flightStartTime>1175731200</flightStartTime>
    <width>1920</width>
    <height>1080</height>
    <thumbnail height="0" width="0">http://ak.c.ooyala.com/12345678901234567890/promo121984023</thumbnail>
    <stat>
    </stat>
  </item>
</list>