Content signing¶

Dashboard setting¶

Signing of your content can be enabled through a setting in the account tab of the dashboard. The setting is called content security and has the following options:

• Allow video downloads and player embeds: this is the default option. Both your videos and players will be publicly accessible.
• Secure video downloads, allow player embeds: Your videos will only be accessible using valid signed URLs. Your players will remain publicly accessible.
• Secure video downloads and player embeds: Both your videos and players will only be accessible through valid signed URLs.

Access to thumbnails, feeds and previews cannot be restricted; they are always publicly available. When access is restricted for videos, the feeds will contain invalid video links. When access to players is restricted, the previews will contain invalid player embeds.

Signed links¶

A video or player URL can be signed by appending two querystring parameters to the regular URL. Here’s two examples and a description of the parameters:

• http://content.bitsontherun.com/videos/nPripu9l.mp4?exp=1371335018&sig=a0124258c73177029d09bb82c6608392
• http://content.bitsontherun.com/players/nPripu9l-ALJ3XQCI.js?exp=1371335035&sig=f42664403879f61ece4f444d225ce507

exp

The expiration date of the URL, as a UNIX timestamp (e.g. 1271338236). Typically, generated URLs should be valid between a minute and a few hours.

sig

A signature that is used to authorize the request. This signature is an MD5 digest of the contentserver path, the expiration date and the account secret:

md5(CONTENT_PATH:EXPIRATION_STAMP:ACCOUNT_SECRET)

Here’s a small explanation of the three signature parameters:

CONTENT_PATH

This is only the path portion of the URL (e.g. videos/nPripu9l.mp4). No domain and no leading slash.

EXPIRATION_STAMP

This is the expiration date again (e.g. 1271338236).

ACCOUNT_SECRET

This is the shared secret of your Bits on the Run account (e.g. Ksi93hsy38sjKfha9JaheEMp). It can be found in the account tab of the dashboard.

Using signing¶

If you want to deny all public access to your videos or players, all you have to do is enable the security setting. There’ll be no way for a third party to generate signed links, since they do not know your account secret. Your content will remain available for previewing / downloading within the dashboard.

If you want to secure your content but occasionally want to forward a video or player link (e.g. to your clients), you can use a small tool like this demo to manually generate a signed URL. Make sure that links do not expire before your client receives them.

If you want to secure your content, but still want to embed players or offer video downloads on your own site (e.g. if you have a pay-per-view site), then you should implement a small script on your site that automatically generates the signed links. For example, you could use a small PHP function like this one to always generate a valid signed URL:

<?php
function get_signed_player($videokey,$playerkey) {
  $path = "players/".$videokey."-".$playerkey.".js";
  $expires = round((time()+3600)/60)*60;
  $secret = "Ksi93hsy38sjKfha9JaheEMp";
  $signature = md5($path.':'.$expires.':'.$secret);
  $url = 'http://content.bitsontherun.com/'.$path.'?exp='.$expires.'&sig='.$signature;
  return $url;
};

echo "<p>Watch this cool video:</p>";
echo "<script type='text/javascript' src='".get_signed_player('nPripu9l','ALJ3XQCI')."'></script>";
?>

A couple of things to keep in mind when auto-generating signed links:

• Signed links should always be generated serverside. Otherwise your shared secret will be exposed to the client. If you do want to use signed links in javascript or actionscript applications, setup a small serverside script to act as a proxy.
• The shorter you make the expiration dates, the more you lock down your content. If a link has expired, even download tools like Realplayer will not be able to grab the content. However, at a certain point you will run into expiration issues with slow-responding servers or small discrepancies in server time.
• If you have a high-volume website, the extra signature generation step might be a performance issue. In that case, you could cache signed URLs with an interval of e.g. 1 minute. Signed requests do not have to be unique.

Error handling¶

When unsigned content is requested while signing is enabled, the contentserver will return a 403 Access forbidden HTTP header.

When incorrectly signed content is requested, the contentserver will also return a 403 Access forbidden HTTP header. Signed URLs can be incorrect due to a wrong signature or due to an already expired timestamp.

Note that incorrectly signed URLs will always get a 403 returned and correctly signed URLs will always work. Use this to test and put in place your signing mechanism before actually enabling the security in the dashboard.