URL Signing and Validation

Table Of Contents

URL Signing and Validation

Introduction

URL Signing Components

Supported Protocols and Media

Configuring the CDS for URL Signing

URL Signing Script

Example of a Python URL Signing Script

Running a Python URL Signing Script

Importance of Device Synchronization

Understanding the Signing Procedure

URL Signing and Validation

---

This appendix describes the URL signing and validation method for the Cisco Internet Streamer CDS. This appendix contains the following sections:

•Introduction

•Configuring the CDS for URL Signing

•URL Signing Script

•Understanding the Signing Procedure

Introduction

The Cisco Internet Streamer CDS accepts and fulfills requests for video content from client devices in the form of content URLs. Content and service providers, in order to protect their copyright and fulfill their licensing obligations, often need to restrict access to content and limit viewing times. Basic authentication and authorization at the portal (for example, username and passwords) can help achieve this objective by restricting content access to authorized users. However, because URLs are inherently open, users (once authenticated at the portal) could potentially share these content URLs with other possibly unauthorized users, or continue to access the content beyond the allotted time.

Cisco Internet Streamer CDS 2.2 provides the infrastructure to sign and validate content URLs, restricting access to some users and limiting viewing times.

URL Signing Components

One of the easiest ways to restrict content access to a particular user is to embed, within the content URL, the client IP address of the user for whom the content access was authorized. Similarly, to ensure that the content expires after a predetermined time, an expiry timestamp could be embedded. These values can then be validated against the actual client sending the request and the current time at the Service Engine serving the request. If either of the two validations fail, the request is rejected.

However, because any of these strings in the URL could potentially be edited manually and circumvented by any knowledgeable user, it is important to generate and attach a signature to the URL. This can be achieved by attaching a keyed hash to the URL, using a secret key shared only between the signer (the portal) and the validating component (CDS).

CDS has incorporated an open and well-documented signing mechanism that uses standard hashing schemes. The URL signing mechanism offers the flexibility to either use the provided signing script, or you can develop a signing application in the platform or language of your choice, as long as it adheres to the specified format.

For signing and validation of the URL, the CDS relies on a set of one or more secret keys shared between the portal and the devices within the CDS.

Supported Protocols and Media

The URL signing and validation is supported across all CDS protocol engines; Windows Media Engine, Movie Streamer Engine, Flash Media Streaming Engine, and Web Engine.

Configuring the CDS for URL Signing

To enable validation of URLs in the CDS, the following tasks must be completed on all participating Service Engines:

•Configure shared secret keys

•Configure pattern-lists to match URLs, domain names , or both

•Configure rules to validate URLs matching the above pattern-lists

•Enable rules processing

Details on these configurations are available in the Cisco Internet Streamer CDS 2.0-2.2 Software Configuration Guide. See the "Related Publications" section on page ix for links to documentation online.

The CDS URL signing infrastructure supports multiple keys. Different pieces of content, with different URLs, can be signed by different keys. Keys are stored as a key matrix and identified (indexed) by a key ID owner and a key ID number.

URL Signing Script

At the portal, URLs can be signed for a particular user (client IP address) and expiry time using a URL signing script. The URL signing script example included in this appendix requires Python 2.3.4 or higher.

Example of a Python URL Signing Script

The following simple Python script demonstrates how to construct and sign URLs for use with the Internet Streamer CDS Release 2.2. This example script produces signatures compliant with the format used by the Internet Streamer CDS.

Depending on where the python binary is installed, you may need to modify the first line of the script. The first line is only necessary if you plan to run the script as an executable. However, if you run the script using the python interpreter, as documented in the "Running a Python URL Signing Script" section, the first line is not required.

#!/usr/local/bin/python

import md5 

import socket 

import time 

import sys 

def sign_url(url,key):

""" Signs url using key and returns the signed URL with the signature appended. """ 

# Generate a MD5 hash of the key string (not the url) 

foo = md5.new(key) 

# Update the hash generated with the url string 

# This effectively means concatenating key and url and generating 

# a hash for the two 

foo.update(url) 

# Get the digest in hex format (human readable) 

return url+foo.hexdigest()

def usage():

""" Prints usage for the URL signing script. """ 

print "Usage:" 

print "python cds-ims-urlsign.py <url> <client-ip> <expiry-delay-seconds> 
<key-id-owner> <key-id-number> <key>" 

print "Example:" 

print "python cds-ims-urlsign.py rtsp://abc.com/content/Apocalypto.mov 171.71.50.123 
120 1 2 pl023MDQlk"

if __name__ == "__main__": 

""" Prints signed URL """ 

if len(sys.argv) < 7: 

usage() 

sys.exit(2) 

url = sys.argv[1] # URL 

client_ip = sys.argv[2] 

delay_seconds = sys.argv[3] # Number of seconds after which URL expires 

ko = sys.argv[4] # Key ID Owner 

kn = sys.argv[5] # Key ID Number 

key = sys.argv[6] # Key 

# Set expiry time as current time (seconds since epoch) + delay 

et = time.time() + int(delay_seconds) 

expires = str(int(et)) 

if url.find('?')==-1: 

url2 = url + "?" 

else: 

url2 = url + "&" 

# This string format is fixed and should not be modified. 

# Note that we sign even the "&US=" part that will point to the signature 

url2 = url2 + "IS=0"+"&ET="+expires+"&CIP="+client_ip+"&KO="+ko+"&KN="+kn+"&US="; 

url3 = sign_url(url2,key) 

#print url 

#print url2 

print url3

Running a Python URL Signing Script

The example script, call it "cds-ims-urlsign.py," can be used as follows:

python cds-ims-urlsign.py url client-ip expiry-delay-seconds key-id-owner key-id-number key

url	URL to sign.
client-ip	IP address of the client for which this URL is being signed, in dotted decimal format (A.B.C.D). The signed URL will be rejected if sent from any other client if signature validation is enabled.
expiry-delay-seconds	Seconds (from now) when the URL expires. The request will be rejected if the time period has passed when the URL is validated at the device. See the "Importance of Device Synchronization" section.
key-id-owner	This argument provides the first index into the key matrix.
key-id-number	This argument provides the second index into the key matrix.
key	Shared secret key corresponding to this ordered pair (key-id-owner, key-id-number).

To use the URL signing script on the URL "rtsp://cisco.com/content/CiscoCDS.mov," for the client IP address of 171.71.50.123, with expiry delay of 120 seconds, key-id owner of 1, key-id-number of 2, and a key of kwnx90KGP, enter the following:.

python cds-ims-urlsign.py rtsp://cisco.com/content/CiscoCDS.mov 171.71.50.123 120 1 2 kwnx90KGP

The signed URL is the following:

rtsp://cisco.com/content/CiscoCDS.mov?IS=0&ET=1209422976&CIP=171.71.50.123&KO=1&KN=2&US=f0
8b56f46075813e44b2d4888628a471

Importance of Device Synchronization

URL expiry time validation relies on the assumption that the clocks are synchronized on the server running the signing application and the Service Engines validating the URL. Use of Network Time Protocol (NTP) on all devices, including the device running the signing application or script, is highly recommended.

It is not sufficient to merely have the same local times on two devices while their time zones differ.

For example, the following two devices are not synchronized:

•Device 1:

–Local Time: 11:00:59 PM, October 12, 2008

–Time Zone: PST

•Device 2:

–Local Time: 11:00:59 PM, October 12, 2008

–Time Zone: EST

The following two devices are synchronized:

•Device 1:

–Local Time: 11:00:59 AM, October 12, 2008

–Time Zone: PST

•Device 2:

–Local Time: 2:00:59 PM, October 12, 2008

–Time Zone: EST

Understanding the Signing Procedure

To customize the URL signing script for your portal, or to write your own signing application in the platform and language of your choice, and still be able to validate URLs within the CDS, follow the steps explained in this section.

The URL signing script performs these steps when processing an unsigned URL:

1. Checks if the URL already contains a query string.

If the URL does not contain a query string, appends a question mark (?).

If the URL does contain a query string, appends an ampersand (&).

2. Appends the string IS=0. This string is for legacy support with some CDS components that use both internal (within CDS) and external (portal) signing mechanisms.

3. Appends the string &ET=.

4. Gets the current time in seconds since epoch (as an integer). Adds the expiry time in seconds as an integer and appends this integer.

5. Appends the string &CIP=.

6. Appends the requesting client IP address, using dotted decimal format.

7. Appends the string &KO=.

8. Appends the key ID owner corresponding to the key being used.

9. Appends the string &KN=.

10. Appends the key ID number corresponding to the key being used.

11. Appends the string &US=.

12. Stores this as url2; for example:

"rtsp://cisco.com/content/CiscoCDS.mov?IS=0&ET=1209422976&CIP=171.71.50.123&KO=1&KN=2&US="

13. Generates an MD5 hash of the key being used.

14. Updates the generated hash with url2.

15. Converts the hash to its equivalent human readable hex digest; for example:

f08b56f46075813e44b2d4888628a471

16. Appends the hex digest to url2. The URL signing is complete.