Resource URI

A resource URI is a pointer to a media object (eg. a broadcast or an uploaded image). By default, media objects can only be accessed by their owner. The owner may share the media object by signing its resourceUri and handing the result to someone else, i.e. "delegating view access".

The Bambuser player SDKs for Android and iOS, as well as the web player, require a signed resourceUri as input.

Your backend, which is aware of your auth scheme, should decide whether and when a given client should be privileged to access a given media object, and hand it a corresponding signed resourceUri as necessary.

You can either make your backend capable of signing a resourceUri with your daId/daSecret credential pair, or request pre-signed resourceUris from the REST API.

URI schema

When bootstrapping a player with a Bambuser broadcast, the resourceUri should have the following structure:

https://cdn.bambuser.net/broadcasts/:broadcastId?:signature

You can discover your broadcastIds through any of the following sources:

Pre-signed resource URIs

If you don't need custom authorization and simply want to let anybody access a media object with a single resourceUri the REST API for broadcast metadata provides pre-signed resourceUris which may be used more than once and do not expire.

Similarly, the REST API for image metadata provides image URLs which don't have any access restrictions.

Signing a resource URI yourself

The access control behaviour for a resource URI can be modified by certain parameters defined by a protocol called Delegation API (DA).

A resourceUri signed by your backend is by default valid for a single view attempt which must begin within one hour. If desired, this behavior can be modified by including da_ttl and da_static as signature parameters. The default behavior is well suited for private limited sharing, intranets, serving content behind paywalls etc.

Requirements

  • The broadcastId for a broadcast created by one of your applications
  • A set of DA credentials; a da_id and a da_secret_key, which you can find on the Developer page on the Bambuser site.

Creating a signature

  1. Start by constructing a resourceUri using the broadcastId for the broadcast you want to access. It should look something like this:
https://cdn.bambuser.net/broadcasts/948bca3e-a4af-471d-9f4a-2f51d246a10a
  1. Select appropriate values for each of the DA parameters listed below and add them as a query string to your resourceUri. The result could look like this (line breaks added for better visibility):
https://cdn.bambuser.net/broadcasts/948bca3e-a4af-471d-9f4a-2f51d246a10a
  ?da_id=MY_DA_ID
  &da_timestamp=1471360487
  &da_nonce=0.7911932193674147
  &da_signature_method=HMAC-SHA256
  1. Generate a signature

Add GET to the start of the result from the previous step. Then produce a hex digest of the HMAC (SHA-265) of the string using your da_secret_key as the secret key. The result of this operation is the signature.

Javascript

const crypto = require('crypto');
const MY_DA_ID = '';
const MY_DA_SECRET_KEY = '';
let stringToSign = 'GET https://cdn.bambuser.net/broadcasts/948bca3e-a4af-471d-9f4a-2f51d246a10a';
stringToSign += '?da_id=' + MY_DA_ID;
stringToSign += '&da_timestamp=' + Math.floor(Date.now() / 1000);
stringToSign += '&da_nonce=' + Math.random();
stringToSign += '&da_signature_method=HMAC-SHA256';
const signature = crypto.createHmac('sha256', MY_DA_SECRET_KEY)
  .update(stringToSign)
  .digest('hex');

Python

import hmac
import hashlib
import time
import random
MY_DA_ID = ''
MY_DA_SECRET_KEY = ''
stringToSign = 'GET https://cdn.bambuser.net/broadcasts/948bca3e-a4af-471d-9f4a-2f51d246a10a'
stringToSign += '?da_id=' + MY_DA_ID
stringToSign += '&da_timestamp=' + str(int(time.time()))
stringToSign += '&da_nonce=' + str(random.random())
stringToSign += '&da_signature_method=HMAC-SHA256'
signature = hmac.new(MY_DA_SECRET_KEY, stringToSign, hashlib.sha256).hexdigest()

PHP

<?php
define('MY_DA_ID', '');
define('MY_DA_SECRET_KEY', '');
$stringToSign = 'GET https://cdn.bambuser.net/broadcasts/948bca3e-a4af-471d-9f4a-2f51d246a10a';
$stringToSign .= '?da_id=' . MY_DA_ID;
$stringToSign .= '&da_timestamp=' . time();
$stringToSign .= '&da_nonce=' . rand();
$stringToSign .= '&da_signature_method=HMAC-SHA256';
$signature = hash_hmac('SHA256', $stringToSign, MY_DA_SECRET_KEY);
  1. Finally, add the signature to the end of the resourceUri as a query parameter named da_signature (line breaks added for better visibility):
https://cdn.bambuser.net/broadcasts/948bca3e-a4af-471d-9f4a-2f51d246a10a
  ?da_id=MY_DA_ID
  &da_timestamp=1471360487
  &da_nonce=0.7911932193674147
  &da_signature_method=HMAC-SHA256
  &da_signature=8dca3b1eae750b5b4d88e4e7dd1bfd3f6c605faff13302276af0da883c0d7642

You now have a signed resourceUri!

Delegation API parameters

name type description
da_id string Your public Delegation API id which corresponds to your secret key.
da_timestamp integer Timestamp, given as seconds since January 1 1970 (UTC). Used as a security measure, to invalidate the signature a reasonable number of minutes after the request is signed.
da_nonce string A random value chosen by you. Choose a different nonce value for each request. For signed requests with unique nonce values, the Bambuser backend will block attempts to replay the request after being used once.
da_signature_method string Indicates which algorithm was used to generate the signature. Use the value HMAC-SHA256.
da_ttl integer Duration, given as seconds, defining how long the signed URI is valid, counting from da_timestamp. The default value is 3600 seconds. TTLs of less than a few minutes is generally not recommended due to potential synchronization issues between server clocks.
da_static boolean When set, this parameter makes the signed URI valid for repeated use, effectively making the Bambuser backend ignore any da_nonce.

Delegation API signature

The signature is a Hex digest of the HMAC of your secret key and an SHA-256 hash of a string which represents the request the client is about to make, including all da_-prefixed parameters excluding da_signature. The request string consists of the HTTP verb followed by space, followed by the domain, path and the query string.

Each DA parameter should be appended to the query string, which is then signed, and the resulting da_signature must be appended as the last parameter in the query string.