PlayReady App Creation Tutorial

(1)

PlayReady App Creation Tutorial

Version 0.93

(2)

1. OVERVIEW ... 4

2. INTRODUCTION ... 4

2.1. DEVELOPMENT ENVIRONMENT ... 4

2.2. FILES NEEDED FOR A PLAYREADY VIDEO APPLICATION ... 5

3. SAMSUNG TV PLAYREADY SPECIFICATION ... 5

3.1. PLAYREADY AND WMDRM10 FOR PORTABLE DEVICES ... 5

3.2. DIRECT LICENSE ACQUISITION (DLA) ... 5

3.3. SILENT LICENSE ACQUISITION WITH USER CUSTOM DATA ... 5

3.3.1. Set Cookie in HTTP Header ... 6

3.3.2. Set User Custom Data ... 6

3.4. POST-DELIVERY AND PRE-DELIVERY LICENSE ACQUISITION ... 7

3.5. WEB INITIATORS ... 8

3.6. DOMAIN JOIN AND LEAVE ... 8

3.7. EMBEDDED LICENSE ... 8

3.8. SECURITY VERSION /CLIENT VERSION /USER-AGENT ... 8

3.9. SECURITY LEVEL ... 9

3.10. DELETE LICENSE ... 9

4. API GUIDELINE ... 10

4.1. PLAYREADY URLFORMAT ... 11

4.2. SET COOKIE IN HTTPHEADER ... 11

4.3. SET USER CUSTOM DATA ... 11

4.4. CHANGING LICENSE SERVER URL... 11

4.5. PROCESS WEB INITIATORS ... 12

4.6. JOIN DOMAIN ... 12

4.7. LEAVE DOMAIN ... 13

(3)

Preface

 Purpose of Document

.

This document is a tutorial that is aimed at application developers for Samsung Smart TVwho plan to use PlayReady Technology for protecting their streaming content. This document focuses on the features supported by Samsung TV and does not provide a detailed description about PlayReady Technology itself. For more information about the technology, please refer to the official Microsoft Web Site (http://www.microsoft.com/playready/default.mspx).

It is recommended that you read Application Development Guide for Samsung Smart TV(hereinafter referred to as "the Guide") first. This document provides references to the Guide for your understanding.

 Target Readers

.

This document is aimed at programmers who have used web development languages such as HTML, CSS and JavaScript, and will be even more helpful for those who have web development experience. This document has been written on the assumption that readers have a background in Microsoft DRM and have already read the Guide.

(4)

1. Overview

This document will go step by step through the development of an application that features a PlayReady video playback. The PlayReady features of Samsung TV are described in section 3 and how to implement those features using Samsung TV Apps SDK is described in section 4.

2. Introduction

PlayReady is a content access and protection technology that is the successor to WMDRM. It provides new advanced and frequently-requested features, such as domain control, embedded licenses, and the ability to protect a wide range of content types and formats. Also, it provides backward compatibility with WMDRM.

Samsung TV released in 2011 supports PlayReady Technology, whereas the previous product only supports WMDRM. Since PlayReady provides backward compatibility with WMDRM, Samsung TV can acquire content from both existing WMDRM-based services and new PlayReady-based services.

In order to develop the PlayReady video Application, developers are required to have background knowledge such as HTML, JavaScript and CSS. There will be no explanation about HTML, JavaScript or CSS provided in this document. Developing applications suited for TVs is different from developing applications on PCs in several aspects. You can get more information on this from the Guide. This document explains each development stage with the source code and analyzes how each code is completed. But please note that the code snippets provided is indicative and detailed source code is not provided in the document.

2.1. Development environment

The application uses Samsung TV Apps SDK made by Samsung to create the application. With use of the emulator provided with the SDK, you can operate your application before actually putting it in your TV, note that the actual PlayReady playback is not supported in the SDK as per the current

version of SDK, this can only be tested on TV.

It is possible to run the application on a real Internet@TV device (for example, a TV) using the "User Application" features. For details of this process please see the document "User Application". Before porting the application on real target, ensure that the target is capable of playing a PlayReady video.

(5)

2.2. Files needed for a PlayReady Video Application

You will be provided with the basic source code for the PlayReady video application. Unzip the files, and refer to section 3.3 to locate them in the appropriate places.

Please note that this tutorial does not supply any video files for playback for copyright reasons.

3. Samsung TV PlayReady Specification

This section briefly explains the PlayReady features supported by Samsung TV.

3.1. PlayReady and WMDRM 10 for Portable Devices

Samsung TVs launched in 2011 support Microsoft PlayReady Technology. Microsoft PlayReady provides backward compatibility with Windows Media DRM, therefore Samsung device can acquire content from both existing WMDRM 10 for Portable Devices and new Microsoft PlayReady-based services.

3.2. Direct License Acquisition (DLA)

Since Samsung TV can acquire a license directly from a license server, we only support DLA mode.

3.3. Silent License Acquisition with User Custom Data

We don’t support any intermediate step asking for user input during license acquisition process.

o “Direct License Acquisition” (“DLA”) means the ability to acquire license directly from a license server over an IP network rather than through a proxy client.

o “Indirect License Acquisition” (“ILA”) means the ability to acquire license indirectly through a proxy client such as a personal computer by using Media Transfer Protocol over a USB connection.

In silent license acquisition, whenever a license challenge is received by a license server, the license server responds by sending a license response to the device. There are some instances where the license server may need additional information from the user before issuing a license. These instances are called non-silent license

acquisition scenarios; for example, a user's identity is not authenticated and therefore needs to enter a user

(6)

Instead, you can add any custom data generated in authentication or payment stage to the license challenge message.

If your service is based on WMDRM10, you can set your custom data using cookie property as described in 3.3.1. If your service is based on PlayReady, you can set the custom data in the cookie of HTTP Header as described in 3.3.1 or set the data in challenge message as described in 3.3.2. The data is used when calling Drm_LicenseAcq_GenerateChallenge function. Please refer to the PlayReady Specification for more information.

3.3.1. Set Cookie in HTTP Header

You can set a string which should be contained in HTTP Header of license challenge message using SetPlayerProperty function. Please refer to section 4 for the detailed API usage.

Here is an example of HTTP Header of the license challenge message with cookie.

3.3.2. Set User Custom Data

This feature is only available in PlayReady-based service.

You can set a custom data which should be contained in challenge message using SetPlayerProperty function. Please refer to section 4 for the detailed API usage.

Here is an example of license challenge message with user custom data.

POST /Janus/testcases/9TC1.asp HTTP/1.0 Host: wmtap.smdisp.net User-Agent: PlayReadyClient Content-Type: application/x-www-form-urlencoded Pragma: no-cache Cookie :MyCookie Content-Length: 22742

(7)

3.4. Post-delivery and Pre-delivery License Acquisition

Post-delivery : Samsung TV invokes License Acquisition when the media file is played. After the header of the media file is processed, it acquires a license based on the data contained within the header of the file.

o By default, Samsung TV uses license acquisition URL parsed from the header. But, you can modify or replace the URL by using SetPlayerProperty function. Please refer to section 4 for the detailed API usage.

Pre-delivery: If you want to acquire a license before the media file is available, you can use License Acquisition Web Initiator in PlayReady-based Service.

The most common pattern of acquiring a license is to download a piece of content and acquire a license based on the data contained within the header of the content. This approach is called post-delivery.

An alternative approach is license pre-delivery. Here, the license is acquired for the content before the content available to the client.

<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body><AcquireLicense xmlns="http://schemas.microsoft.com/DRM/2007/03/protocols"> <challenge> <Challenge xmlns="http://schemas.microsoft.com/DRM/2007/03/protocols/messages">

<LA xmlns="http://schemas.microsoft.com/DRM/2007/03/protocols" Id="SignedData" xml:space="preserve"> <Version>1</Version> <ContentHeader><WRMHEADER xmlns=http://schemas.microsoft.com/DRM/2007/03/PlayReadyHeader version="4.0.0.0"> …. </WRMHEADER> </ContentHeader> <ClientInfo> … </ClientInfo> <CustomData>MyCustomData</CustomData> …

(8)

3.5. Web Initiators

Samsung TV supports all defined PlayReady Web Initiators.

You can use ProcessInitiatorsFromXml or ProcessInitiatorsFromUrl to initiate a DRM protocol. Please refer to section 4 for the detailed API usage.

3.6. Domain Join and Leave

Samsung TV can join a specific domain by JoinDomain function or leave the domain by LeaveDomain function. Please refer to section 4 for the detailed API usage.

3.7. Embedded License

Samsung TV is able to parse and playback PlayReady media file which has Embedded License.

3.8. Security Version / Client Version / User-Agent

If your license server checks the values of Security Version, Client Version, or User-Agent in the PlayReady allows a group of devices that are members of a domain to play back all

content that binds to the same domain. Previously, only device-bound licenses could be issued for content. Only one client in a domain needs to acquire a license for a given piece of content, and then the license can be embedded into the content. The content can then be shared and played among all members of the domain.

PlayReady allows an application to store the license for a DRM-protected content file in the PlayReady object of the content file itself. Because the license is stored (or “embedded”) in the content file, it is immediately available, enabling a player

application to decrypt and begin playing the content without first needing to complete the license acquisition process or check the HDS store.

Web initiators are XML document which are sent from the portal to the device to initiate a DRM protocol between client and service. Web Initiators can be sent to initiate a license acquisition, metering, a join domain or a leave domain protocol.

(9)

license challenge request message before issuing license, you should add the following values in your accept list for Samsung TVs.

2010 Products 2011 Products < SECURITYVERSION> 2.4.115.165 2.4.117.27 < CLIENTVERSION> 9.00.00.2778 11.2.0.1404 User-Agent WMDRM_DLA Windows-Media-DRM/11.0.7600.16385 PlayReadyClient

Note that the requirement of minimum security version is not necessary for devices. <SECURITYVERSION> corresponds to the robustness version of the PC client black box, and it is only meaningful when the client is PC application. Enforcing a minimum security version on PCs (includes Silverlight clients) is to ensure that in case of a PC breach only patched PC receive the content. For devices the value is not meaningful because in case of a breach the device certificate itself would have been revoked and the server will just not deliver a license.

3.9. Security Level

Samsung Devices use Security Level 2000 certificates.

3.10. Delete License

After acquiring a valid license from a license server, Samsung TVs store the license in the permanent storage in order not to perform the license acquisition process during the validity period. But, if you want to delete a license after playing a content using the license, you can use the SetPlayerProperty function. The license is deleted when the play is stopped. Please refer to section 4 for the detailed API usage.

(10)

4. API Guideline

2010 Products 2011 Products

WMDRM10 WMDRM10 PlayReady

Set Cookie SetPlayerProperty (1) O * O O

Set User Custom Data SetPlayerProperty (3) X X O

Changing License Server URL SetPlayerProperty (4) X O O

Process Web Initiator ProcessInitiatorsFromUrl

ProcessInitiatorsFromXml

X X O

Join/Leave Domain JoinDomain

LeaveDomain

X X O

Delete License SetPlayerProperty (6) X O** O**

* Supported after T-INFOLINK-2010-1009 ** Supported after T-INFOLINK-2011-1002

(11)

4.1. PlayReady URL Format

If you want to play PlayReady/WMDRM protected content, you should add predefined postfix “|COMPONENT=WMDRM” to your original URL.

4.2. Set Cookie in HTTP Header

You can use SetPlayerProperty before calling StartPlayback() function.

You can change the second and third parameters of SetPlayerProperty function to your custom data like DUID or tokens which is not an actual cookie set by Server. But, note that your license server finds the value in the cookie property in HTTP Header of license challenge message.

4.3. Set User Custom Data

4.4. Changing License Server URL

playerPlugin.InitPlayer(url|COMPONENT=WMDRM); playerPlugin.SetPlayerProperty (4, serverurl, serverurl.length); playerPlugin.StartPlayback();

playerPlugin.InitPlayer(url|COMPONENT=WMDRM);

playerPlugin.SetPlayerProperty (3, customdata, customdata.length); playerPlugin.StartPlayback();

playerPlugin.InitPlayer(url|COMPONENT=WMDRM);

playerPlugin.SetPlayerProperty (1, document.cookie, document.cookie.length); playerPlugin.StartPlayback();

var url = http://www.server.com/a.wmv;

var playerPlugin = document.getElementById("pluginPlayer"); playerPlugin.InitPlayer(url|COMPONENT=WMDRM); playerPlugin.StartPlayback();

(12)

4.5. Process Web Initiators

You can use ProcessInitiatorsFromUrl to pass the Web Initiator URL. Samsung TV sends HTTP GET Request to the url and parse the result.

Or, you can use ProcessInitiatorsFromXml to pass the xml string which complies with the XML Schema defined by PlayReady Technology.

4.6. Join Domain

You can use JoinDomain to join a specific domain.

SefPluginPlayReady = document.getElementById('PluginSefPlayReady'); var certserver = "http://www.yourdomainserver”;

var serviceid = "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}"; var accountid = "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}"; var customdata = “customdata”;

SefPluginPlayReady = document.getElementById('PluginSefPlayReady'); SefPluginPlayReady.Open("PlayReadyDrm", "1.000", "PlayReadyDrm");

SefPluginPlayReady.Execute("JoinDomain", certserver, serviced, accounted, customdata, customdata.length); SefPluginPlayReady.Close ();

var xml = “<?xml version=\”1.0\”…”;

SefPluginPlayReady.Execute (“ProcessInitiatorsFromXml”, xml, xml.length); SefPluginPlayReady.Close ();

var url =”http://www.yourserver.com/initiators/LicenseAcquisitionInitiator.xml”;

SefPluginPlayReady.Execute (“ProcessInitiatorsFromUrl”, url); SefPluginPlayReady.Close ();

(13)

4.7. Leave Domain

You can use LeaveDomain to leave a specific domain.

4.8. Delete License

playerPlugin.InitPlayer(url|COMPONENT=WMDRM); playerPlugin.SetPlayerProperty (6, NULL, 1);

playerPlugin.StartPlayback();

SefPluginPlayReady = document.getElementById('PluginSefPlayReady'); var certserver = "http://www.yourdomainserver”;

var serviceid = "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}"; var accountid = "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}"; var customdata = “customdata”;

SefPluginPlayReady.Execute("LeaveDomain", certserver, serviced, accounted, customdata, customdata.length); SefPluginPlayReady.Close ();