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:
•Configuring the CDS for URL Signing
•URL Signing Script
•Understanding the Signing Procedure
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 "Configuring URL Signing" section on page 4-23 and the "Configuring Service Rules" section on page 4-15.
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.
""" Signs url using key and returns the signed URL with the signature appended. """
# Generate a MD5 hash of the key string (not the url)
# Update the hash generated with the url string
# This effectively means concatenating key and url and generating
# Get the digest in hex format (human readable)
""" Prints usage for the URL signing script. """
print "python cds-ims-urlsign.py <url> <client-ip> <expiry-delay-seconds>
<key-id-owner> <key-id-number> <key>"
print "python cds-ims-urlsign.py rtsp://abc.com/content/Apocalypto.mov 126.96.36.199
120 1 2 pl023MDQlk"
if __name__ == "__main__":
""" Prints signed URL """
delay_seconds = sys.argv # Number of seconds after which URL expires
ko = sys.argv # Key ID Owner
kn = sys.argv # Key ID Number
# Set expiry time as current time (seconds since epoch) + delay
et = time.time() + int(delay_seconds)
# 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)
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 to sign.
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.
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.
This argument provides the first index into the key matrix.
This argument provides the second index into the key matrix.
Shared secret key corresponding to this ordered pair (key-id-owner, key-id-number).
In addition to the above six variables, the current time is used to generate the URL signing, so even if the same values were used for the above six variables, the signed URL would be different.
To use the URL signing script on the URL "rtsp://cisco.com/content/CiscoCDS.mov," for the client IP address of 188.8.131.52, 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 184.108.40.206 120 1 2 kwnx90KGP
The signed URL is the following:
Note The above signed URL is only an example. The MD5 algorithm generates a different message digest each time. For more information on the MD5 algorithm see the IETF RFC 1321.
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:
–Local Time: 11:00:59 PM, October 12, 2008
–Time Zone: PST
–Local Time: 11:00:59 PM, October 12, 2008
–Time Zone: EST
The following two devices are synchronized:
–Local Time: 11:00:59 AM, October 12, 2008
–Time Zone: PST
–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:
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:
16. Appends the hex digest to url2. The URL signing is complete.