Digital Rights Management (DRM)

1. DRM Scenarios

You can use DRM to help you deliver audio and video content that is more secure and better protected from unauthorized capture and redistribution. This protection can be integrated into a variety of business scenarios that include:

• Online Scenarios: These scenarios require users to be online while they play back the media content:

  • Live Streaming: Live streaming (also known as "true streaming") sends content directly to the computer or device without saving the file to a hard disk. A live stream is only available while it is being broadcast. Internet television and radio are examples of live streaming.

  • Progressive Download: Progressive download lets users play back the media while it is downloading. The main difference between progressive download and live streaming—from a user's point of view—is that progressively downloaded content is stored on the user's computer or device, at least temporarily.

• Offline Scenarios: These scenarios allow users to be offline while they play the content. They do require the offline Silverlight runtime to be installed on a user's computer or device, and they do require the user to be online—at least intermittently—in order to initially download the content and renew subscriptions.

  • Download File Offline (onetime purchase): The user downloads the content from the Internet and later plays it by using an offline Silverlight player. For example, an online video store charges customers to download a video file, which users can play back in an offline Silverlight player whenever they want. The DRM software can restrict redistribution of the video file to one or more devices (see Domains later in this article).

  • Rental: You can specify time limits in your DRM licenses in order to limit playback of content. For example, an online video store might offer their videos for rent. Once the rental is purchased and the license downloaded, the license will expire 30 days after it is issued or 24 hours after content is first played, whichever occurs first.

  • Subscription: You can enable customers to playback content based on a subscription model. For example, customers of the online video store pay a monthly fee to watch up to 100 hours of television content online and download up to 20 episodes. In order to renew their subscription, they need to pay the monthly fee and connect to the service at least once a month because the subscription license expires every 45 days.

2 Silverlight DRM Online Scenarios

The following sections explain how to enable online Silverlight DRM scenarios. Many of the concepts introduced here also apply to offline scenarios; however, offline scenarios, such as rentals and subscriptions, are examined later in Silverlight DRM Offline Scenarios.

This section reviews the minimum components that are needed to play back DRM content in Silverlight. These components apply to both online and offline scenarios; however, some scenarios require additional components, which are covered in later sections.

2.1 Silverlight DRM Online Conceptual Overview

The following diagram summarizes the processes that are needed for Silverlight to play back DRM content online as well as the client/server interactions that are needed to facilitate those processes. Later, each of these steps is discussed in greater detail.

Note:
If the computer that is attempting to play the content already has a license, it might not be necessary to go through the license acquisition process again; rather, the existing license could be used to allow playback.

1. Silverlight Client Accesses Content

2. Is the User’s Computer Individualized?

3. Silverlight Requests License

4. Client Needs to Join Domain? (Optional)

5. Copy License to Persistent Licence Store (Optional)

6. Play Back Content

2.2 PlayReady vs. WMDRM

The Silverlight client can use two forms of DRM protected content: the traditional Windows Media Digital Rights Management 10 (WMDRM 10) and the newer PlayReady. This flexibility enables existing content that is encrypted by using the WMDRM 10 SDK to play back within both Silverlight and other Windows Media playback software that supports DRM (such as Windows Media Player), and Silverlight-only media to offer a higher degree of content protection.

Note:
WMDRM uses different licenses than PlayReady uses. For example, if you want users to play a given DRM-protected video on both a Windows Media Player or on a Silverlight player, you need two licenses, one for each means of playback.

Note:
PlayReady is not used only in Silverlight. For more information about PlayReady, see PlayReady Whitepaper.

Note:
Although Silverlight can play PlayReady and WMDRM-packaged content, it does not support the entire ecosystems of these technologies. In addition, in order to play WMDRM-packaged content in Silverlight, you need a PlayReady server (see the earlier diagram).

2.3 Limitations When Using Silverlight DRM

Even if you plan to encrypt content by only using WMDRM, it is important to note that you need at least one PlayReady License Server to distribute licenses to the Silverlight client. Also note that Silverlight DRM currently supports only a portion of PlayReady features. The following is a list of important limitations when using Silverlight DRM:

• Silverlight does not support all the file types that PlayReady does. Silverlight only supports playback of DRM-encrypted VC1, WMA, WMA pro, h.264, and AAC streams.

2.4 Considerations for Using PlayReady Encryption vs. WMDRM Encryption

When setting up architecture for using DRM with Silverlight, keep in mind these considerations:

• If you are streaming content, are you encoding and streaming in real-time from live sources, or are you streaming pre-encrypted files on demand?

• Are your customers playing content using Silverlight or are they also using Windows Media Player?

• Do you have a large library of WMDRM-packaged content (packaged using the WMDRM SDK) that you want to serve to Silverlight customers or can you package all of your content using PlayReady?

• Do you want to use the PIFF format? PIFF is supported when using PlayReady.

Regardless of these considerations, if you want to serve DRM content to Silverlight, you need to purchase at least one PlayReady License Server; however, answering these questions can impact whether you can use only PlayReady packaging or whether you also need to handle WMDRM-packaged content in your overall DRM solution.

• Streaming Content: If you want to encode streaming content in real-time from live sources using PlayReady, you can use a third party solution. Alternatively, you can use WMDRM in this scenario. See Playing WMDRM Content in Silverlight later in this topic for possible solutions for integrating WMDRM with Silverlight. If you are using MediaStreamSource which is used in Silverlight to support adaptive streaming, you must use PlayReady packaged content.

• Client Player: If your customers are only using Silverlight to playback DRM, then you can package everything with PlayReady; however, WMDRM encryption is required for customers who are also targeting Windows Media Player clients.

• Your Content Library: Regardless whether you are only playing content in Silverlight, if you do not want to package your content using PlayReady, you need to create a DRM solution that takes into account WMDRM-packaged content.

Note:
Silverlight does not support WMDRM content with script stream (script streams provide text with the stream, such as with closed captioning). If you play WMDRM content with script stream, the audio and video play as usual but the script stream is ignored.

2.5 Playing WMDRM Content in Silverlight

The following figure conceptualizes how an existing WMDRM-packaged content library that serves non-Silverlight (legacy WMDRM) clients can be used with Silverlight clients.

In order to include the library, you need to include some logic on the Silverlight client to route the license request to the proper PlayReady License Server (see Point to DRM Content from a Silverlight Application later in this topic).

2.6 Integrating DRM in Silverlight

For streaming or progressive download, the following steps are needed to integrate DRM into Silverlight:

1. Set up the necessary server infrastructure to serve up DRM-protected content.

2. Point to this protected content from your Silverlight application using MediaElement.

3. Handle expected errors (for example, when the user does not allow DRM content).

4. If needed, subclass the LicenseAcquirer or DomainAcquirer class to gain custom business logic.

Note:
For WMDRM content, a URL override will be needed to point the license acquisition to the correct PlayReady license server. This is due to the fact that WMDRM content most likely will not contain a PlayReady license server in its WRMHeader.

2.7 Set Up Server Infrastructure

Before using DRM, you must first package the content you want to protect and make it available to clients from a distribution server. You do this by using packaging software. There are several options for packaging content. Two of these options include:

• WMDRM 10 SDK.

• PlayReady Server SDK.

To learn more about these technologies and associated server configurations, see PlayReady vs. WMDRM earlier in this topic.

When you encrypt and package your content, you specify a License Acquisition URL (LAURL). You have the opportunity in the Silverlight application to override this value before sending the License Challenge to a License Server. This is particularly useful if you have one library of WMDRM-packaged content and want to serve that content to both Silverlight and Windows Media Player clients. (See Playing WMDRM Content in Silverlight earlier in this article and Point to DRM Content from a Silverlight Application next in this article).

2.8 Point to DRM Content from a Silverlight Application

If you are using only PlayReady servers to encrypt your encoded content, you can simply point to the content using the Source property of the MediaElement.

<MediaElement x:Name="myMediaElement" Source="myProtectedVideo.wmv" />

You can do this because content that is packaged by using the PlayReady Server SDK includes in its content header the URI location of the licensing server. However, if you are using the WMRM SDK to package your content, the location of the licensing server is not included in the header, and therefore, you need to specify this URI. To do this, use the LicenseServerUriOverride property to specify the URI for the LicenseAcquirer property of the MediaElement to use to find the license:

myMediaElement.LicenseAcquirer.LicenseServerUriOverride = 
    new Uri("https://contoso.com/myLicenseServer.asmx", UriKind.Absolute);

2.9 Detecting the DRM State

You can use the MediaElementState enumeration to detect what state the MediaElement is in, specifically, whether the MediaElement is currently individualizing the Silverlight client or acquiring a license (see Silverlight DRM Online Conceptual Overview earlier in this topic). One reason for detecting these states is to allow you to give feedback to the user about what is going on while the MediaElement prepares to play the content. For example, you can inform the user when individualization is taking place or when a license is being requested by using a TextBlock, as in the following example.

if (myMediaElement.CurrentState == MediaElementState.Individualizing)
{
    myStateTextBlock.text = "Downloading DRM Client";
}
else if(myMediaElement.CurrentState == MediaElementState.AcquiringLicense)
{
    myStateTextBlock.text = "Aquiring License";
}

2.10 Error Handling

When using DRM in Silverlight, users might receive a number of errors. It is important that developers anticipate these errors and display appropriate messages so that users understand why playback is not working the way they expect.

For example, users might receive a DRM-specific error when they opt to disable DRM by going into the Silverlight Configuration dialog box and clearing the checkbox shown in the following illustration.

Disabling DRM prevents the user’s client from requesting individualization from Microsoft Individualization Servers (see Silverlight DRM Online Conceptual Overview earlier in this topic).

If the MediaElement attempts to play DRM content in this scenario, the MediaElement raises a new MediaFailed event with the following error: 6008 DRM_E_INDIVIDUALIZATION_DISALLOWED.

You may want to listen for this error and raise your own custom message when it occurs.

Other DRM-Related Errors

The following table provides a list of errors that are associated with Silverlight DRM. The error numbers listed below are consecutive from 6000 up. Note that in addition to error handling done through the MediaFailed event of the MediaElement (as listed below), synchronous methods and properties can directly throw an exception and asynchronous methods can return exceptions through their corresponding AsyncCompletedEventArgs.

Error Code	Notes
6000	MediaElement failed to play the DRM-protected content.
6001	The individualization component software failed to download to the user’s computer. This error occurs when the MediaElement is in the IndividualizingMediaElementState. One possible reason for this error is that the Silverlight client cannot connect to the Microsoft Individualization Server.
6002	The license acquisition failed. This error occurs when the MediaElement is in the AcquiringLicenseMediaElementState. One possible reason for this error is that the Silverlight Client cannot connect to the license server.
6003	The individualization component software failed to install.
6004	The installation of Silverlight on the client is out of date and needs to be updated.
6005	The processing of the file header failed. For example, the header might be mal-formed.
6006	License processing failed on the Silverlight client. This error occurs when the MediaElement is in the AcquiringLicense MediaElementState.
6007	The PlayReady License server allows the server developer to return an error that is specific to the service. For example, the server might return one of these errors: "You need to pay your bill," "The service is unavailable," or "You have exhausted your monthly stream count." The SOAP exception that is returned from the license server has additional data in the CustomData field that is added by the server. You need to write application logic in the Silverlight application to interpret this. These responses are primarily used when you implement a custom license acquisition (see Add Custom Logic later in this topic).
6008	The user disabled DRM in the Silverlight configuration settings of the client.
6009	The maximum for individualization attempts was exceeded.
6010	A DRM protocol error occurred.
6011	A DRM license acquisition URL override is required.
6012	A DRM license-acquisition redirect error occurred.
6013	The user's HW configuration has changed in a significant way and the DRM state is no longer valid.
6017	The user tried to acquire a license by using a stream (calling AcquireLicenseAsync; however, the stream is in unprotected content.
6021	The DRM system does not support the client OS.
6023	IBX service is not reachable. Some malware / spyware will block calls to *.microsoft.com so ensure that the machine is fully patched and protected.
6030	The license contains an unsupported license protection.
6031	The integrity of the secured video output connection has been compromised or lost.
6032	The secured graphics connection requires renegotiation but could not be renegotiated.
6033	A revoked High-Bandwidth Digital Content Protection (HDCP) device is attached to the video output.
6034	The graphics adapter or the driver has been tampered with.
6035	A new graphics connection was added during playback and playback was halted.
6036	Graphics device's driver certificate is invalid.
6040	The domain is full and does not allow the user to add any more clients to this domain.
6041	The client is not a domain member.
6042	The domain account identifier is unknown.
6208	DRM initialization failed - uninstall/reinstall of Silverlight should address the problem.

Note:
If you are implementing your own custom license acquisition, you must add the headers msprdrm_server_redirect_compat:false and msprdrm_server_exception_compat:false to your HTTP Web requests. If you do not add these headers, errors and redirect messages do not work correctly. See the code example in the adding custom logic section.

Note:
If you start multiple asynchronous operations on the same LicenseAcquirer or DomainAcquirer, an InvalidOperationException is thrown.

2.11 Add Custom Logic

The LicenseAcquirer class is used by the MediaElement to handle acquiring licenses for DRM-encrypted content from the PlayReady License Server. You can subclass the LicenseAcquirer class and add custom logic, such as adding your own custom authentication scheme to the license request.

The following example shows how to override the LicenseAcquirer class (named "ManualLicenseAcquirer") and have a MediaElement use it to acquire the license.

<StackPanel x:Name="LayoutRoot" Background="Gray" Orientation="Vertical">
   <MediaElement x:Name="myME" Height="100"/>
</StackPanel>

public partial class Page : UserControl
{

    public Page()
    {
      InitializeComponent();
      this.Loaded += new RoutedEventHandler(Page_Loaded);
    }

    void Page_Loaded(object sender, RoutedEventArgs e)
    {
      // Test a full fledged manual acquirer

      // Set the LicenseAcquirer of the MediaElement to the custom License Acquirer
      // defined in this sample.
      myME.LicenseAcquirer = new ManualLicenseAcquirer(myME.Name);

      // Set the License URI to proper License Server address.
      myME.LicenseAcquirer.LicenseServerUriOverride = new Uri("https://contoso.com/myLicenseServer.asmx", UriKind.Absolute);
      myME.MediaFailed += new EventHandler<ExceptionRoutedEventArgs>(myME_MediaFailed);

      // Set the source of the MediaElement to the URL of the media encrypted with WMDRM.
      myME.Source = new Uri("https://contoso.com/wmdrm_url.wmv", UriKind.Absolute);
    }

    void myME_MediaFailed(object sender, ExceptionRoutedEventArgs e)
    {
      string errorMessage = "";
      if (e.ErrorException.ToString().Contains(" 6001 "))
      {
          errorMessage = "The individualization component software failed to" +
                         " download to the user’s computer. This error would" +
                         " come up when the MediaElement is in the Individualizing" +
                         " MediaElementState. One possible reason for this error is" +
                         " that the Silverlight client cannot connect the Microsoft" +
                         " Individualization Server.";
      }
      else if (e.ErrorException.ToString().Contains(" 6004 "))
      {
          errorMessage = " The installation of Silverlight on the client is" +
                         " out of date and needs to be updated.";  
      }
      else
      {
          errorMessage = "MediaFailed: " + e.ErrorException.Message + ".";
      }
      System.Windows.Browser.HtmlPage.Window.Alert(errorMessage);
    }

    // makes license request explicitly
    public class ManualLicenseAcquirer : LicenseAcquirer
    {
      private string challengeString;
      string _mediaElementName;

    public ManualLicenseAcquirer(string mediaElementName)
    {
      _mediaElementName = mediaElementName;
    }

    // The default implementation of OnAcquireLicense calls into the MediaElement to acquire a
    //  license. It is called when the Media pipeline is building a topology and will be raised
    // before MediaOpened is raised.
    protected override void OnAcquireLicense(System.IO.Stream licenseChallenge, Uri licenseServerUri)
    {
      StreamReader sr = new StreamReader(licenseChallenge);
      challengeString = sr.ReadToEnd();

      // Need to resolve the URI for the License Server -- make sure it is correct
      // and store that correct URI as resolvedLicenseServerUri.
      Uri resolvedLicenseServerUri;
      if (LicenseServerUriOverride == null)
        resolvedLicenseServerUri = licenseServerUri;
      else
      resolvedLicenseServerUri = LicenseServerUriOverride;

      // Make a HttpWebRequest to the License Server.
      HttpWebRequest request = WebRequest.Create(resolvedLicenseServerUri) as HttpWebRequest;
      request.Method = "POST";

      // Set ContentType through property    
      request.ContentType = "application/xml";

      //  ADD REQUIRED HEADERS.
      // The headers below are necessary so that error handling and redirects are handled 
      // properly via the Silverlight client.
      request.Headers["msprdrm_server_redirect_compat"] = "false";
      request.Headers["msprdrm_server_exception_compat"] = "false";

      //  Initiate getting request stream  
      IAsyncResult asyncResult = request.BeginGetRequestStream(new AsyncCallback(RequestStreamCallback), request);
    }

    // This method is called when the asynchronous operation completes.
    void RequestStreamCallback(IAsyncResult ar)
    {
      HttpWebRequest request = ar.AsyncState as HttpWebRequest;

      // populate request stream  
      request.ContentType = "text/xml";
      Stream requestStream = request.EndGetRequestStream(ar);
      StreamWriter streamWriter = new StreamWriter(requestStream, System.Text.Encoding.UTF8);

      streamWriter.Write(challengeString);
      streamWriter.Close();

      // Make async call for response  
      request.BeginGetResponse(new AsyncCallback(ResponseCallback), request);
    }

    private void ResponseCallback(IAsyncResult ar)
    {
      HttpWebRequest request = ar.AsyncState as HttpWebRequest;
      WebResponse response = request.EndGetResponse(ar);
      SetLicenseResponse(response.GetResponseStream());
    }
  }
}

Public Class Page
    Inherits UserControl
    
    Public Sub New()
        MyBase.New
        InitializeComponent
        AddHandler Loaded, AddressOf Me.Page_Loaded
    End Sub
    
    Private Sub Page_Loaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
        ' Test a full fledged manual acquirer
        ' Set the LicenseAcquirer of the MediaElement to the custom License Acquirer
        ' defined in this sample.
        myME.LicenseAcquirer = New ManualLicenseAcquirer(myME.Name)
        ' Set the License URI to proper License Server address.
        myME.LicenseAcquirer.LicenseServerUriOverride = New Uri("https://contoso.com/myLicenseServer.asmx", UriKind.Absolute)
        AddHandler myME.MediaFailed, AddressOf Me.myME_MediaFailed
        ' Set the source of the MediaElement to the URL of the media encrypted with WMDRM.
        myME.Source = New Uri("http:, contoso.com/wmdrm_url.wmv", UriKind.Absolute);)
    End Sub
    
    Private Sub myME_MediaFailed(ByVal sender As Object, ByVal e As ExceptionRoutedEventArgs)
        Dim errorMessage As String = ""
        If e.ErrorException.ToString.Contains(" 6001 ") Then
            errorMessage = "The individualization component software failed to" & _
                           " download to the user's computer. This error would" & _
                           " come up when the MediaElement is in the Individualizing" & _
                           " MediaElementState. One possible reason for this error is" & _
                           " that the Silverlight client cannot connect the Microsoft" & _
                           " Individualization Server."
        ElseIf e.ErrorException.ToString.Contains(" 6004 ") Then
            errorMessage = "The installation of Silverlight on the client is" & _
                           " out of date and needs to be updated."
        Else
            errorMessage = "MediaFailed: " & _
                        +  e.ErrorException.Message + "."
        End If
        System.Windows.Browser.HtmlPage.Window.Alert(errorMessage)
    End Sub
    
    ' makes license request explicitly
    Public Class ManualLicenseAcquirer
        Inherits LicenseAcquirer
        
        Private challengeString As String
        
        Private _mediaElementName As String
        
        Public Sub New(ByVal mediaElementName As String)
            MyBase.New
            _mediaElementName = mediaElementName
        End Sub
        
        ' The default implementation of OnAcquireLicense calls into the MediaElement to acquire a
        '  license. It is called when the Media pipeline is building a topology and will be raised
        ' before MediaOpened is raised.
        Protected Overrides Sub OnAcquireLicense(ByVal licenseChallenge As System.IO.Stream, ByVal licenseServerUri As Uri)
            Dim sr As StreamReader = New StreamReader(licenseChallenge)
            challengeString = sr.ReadToEnd
            ' Need to resolve the URI for the License Server -- make sure it is correct
            ' and store that correct URI as resolvedLicenseServerUri.
            Dim resolvedLicenseServerUri As Uri
            If (LicenseServerUriOverride Is Nothing) Then
                resolvedLicenseServerUri = licenseServerUri
            Else
                resolvedLicenseServerUri = LicenseServerUriOverride
            End If
            ' Make a HttpWebRequest to the License Server.
            Dim request As HttpWebRequest = CType(WebRequest.Create(resolvedLicenseServerUri),HttpWebRequest)
            request.Method = "POST"
            ' Set ContentType through property    
            request.ContentType = "application/xml"
            '  ADD REQUIRED HEADERS.
            ' The headers below are necessary so that error handling and redirects are handled 
            ' properly via the Silverlight client.
            request.Headers("msprdrm_server_redirect_compat") = "false"
            request.Headers("msprdrm_server_exception_compat") = "false"
            '  Initiate getting request stream  
            Dim asyncResult As IAsyncResult = request.BeginGetRequestStream(New AsyncCallback(RequestStreamCallback), request)
        End Sub
        
        ' This method is called when the asynchronous operation completes.
        Private Sub RequestStreamCallback(ByVal ar As IAsyncResult)
            Dim request As HttpWebRequest = CType(ar.AsyncState,HttpWebRequest)
            ' populate request stream  
            request.ContentType = "text/xml"
            Dim requestStream As Stream = request.EndGetRequestStream(ar)
            Dim streamWriter As StreamWriter = New StreamWriter(requestStream, System.Text.Encoding.UTF8)
            streamWriter.Write(challengeString)
            streamWriter.Close
            ' Make async call for response  
            request.BeginGetResponse(New AsyncCallback(ResponseCallback), request)
        End Sub
        
        Private Sub ResponseCallback(ByVal ar As IAsyncResult)
            Dim request As HttpWebRequest = CType(ar.AsyncState,HttpWebRequest)
            Dim response As WebResponse = request.EndGetResponse(ar)
            SetLicenseResponse(response.GetResponseStream)
        End Sub
    End Class
End Class

3 Silverlight DRM Offline Scenarios

Some users today do not have the available bandwidth to watch high-quality video over the Internet. They do have high speed connections that can be used to download content for viewing later. Other users may want to download a movie to watch later when no network is available, such as on an airplane or at a friend's house that does not have Internet connectivity. Being able to deliver Digital Rights Management (DRM) to content that is offline, but still has increased protection, is key to enabling a variety of content-publishing business scenarios, such as media purchase, subscription, and rental.

3.1 Basic Offline DRM (One-Time Purchase)

Perhaps the simplest offline scenario is when users purchase a piece of content and then download it to their computer to play whenever they want to.

Because the user is attempting to play back protected content offline, license validation also needs to occur offline. To do this, licenses needed by downloaded content are stored on what is called the persistent license store, which is created on the user’s computer during initialization (see Silverlight DRM Online Conceptual Overview earlier in this article). When the user attempts to play back offline content, the content attempts to validate playback by looking for its corresponding license in the persistent license store. You can learn more about enumerating through these licenses in the section Enumerating through Licenses.

3.2 Validate License Before Download

In offline scenarios, users download a content file before they play it. Because downloading a media file can take time and bandwidth, consider validating the user’s license before allowing the download, instead of validating when the user attempts playback. The following example shows how to do this.

The following application uses a key identifier and an authentication token to send a license acquisition request to the license server. The license server responds with a license and the URL from which to download the content.

// Called when the user is online and wants to download some protected content.
public void GetLicensePreDelivery(string customData,
                                     Guid keyId)
{
    Uri licenseServerUrl = new Uri("https://contoso.com/myLicenseServer.asmx");
    LicenseAcquirer acquirer = new LicenseAcquirer();
    acquirer.ChallengeCustomData = customData;

    // Set the License URI to proper License Server address.
    acquirer.LicenseServerUriOverride = licenseServerUrl;
    acquirer.AcquireLicenseCompleted += new EventHandler<AcquireLicenseCompletedEventArgs>(acquirer_Completed);
    acquirer.AcquireLicenseAsync(keyId, ContentKeyType.Aes128Bit, Guid.Empty);
}

The AcquireLicenseAsync call completes after starting the license acquisition but without waiting for the long content download operation to finish. When the license acquisition actually completes, the delegate that is configured on the AcquireLicenseCompleted event is called. In this example, that is the acquirer_Completed method, and it might look something like in the following example.

public void acquirer_Completed(object sender, AcquireLicenseCompletedEventArgs e)
{
    if (e.Error != null)
    {
        // take appropriate action.  Might be retrying for instance.
    }
    else if (e.Cancelled)
    {
        // take appropriate action.  Might be nothing.
    }
    else
    {
        //
        //  We acquired the license successfully, go ahead and download
        //  the content.  Note the service decided to stash the content 
        //  url in the LicenseAcquirer response custom data.
        //
        string contentAcquisitionUrl = e.ResponseCustomData;
        DownloadContent(contentAcquisitionUrl);
    }
}

3.3 Managing Which Computers Can Play Back Content (Domains)

The functionality provided by the Microsoft PlayReady Domain feature is intuitive from an end-user experience: the service provider allows the user to designate a group of computers as a domain. Any computer on the domain can consume Microsoft PlayReady-protected content that is acquired by any other computer on the domain, if they have a domain-bound license for the content. The user may easily add or remove computers from the domain, as long as the total number of computers on the domain does not exceed the limit defined by the service.

The following diagram shows conceptually how domain management fits into the overall DRM process:

The PlayReady domain server (domain controller) is a server that is used to determine what the domain represents (for example, a user, a family, or a group of users) and holds a list of entities that are associated with the domain. The domain server also enforces the policy defining how many computers may join the domain. As always, Domain Controlling, Distribution, and Licensing can all be done on separate servers or on the same server, depending on your performance needs. The preceding diagram shows them as separate servers for the sake of clarity.

Many media applications that use domain bound licenses will want to join the client to the user’s domain the first time the application is run. This allows the service to control the number of clients per user that have access to media content. You cannot enumerate through domains using the Silverlight API. Because of this, you will want to have the application keep state data itself to know whether the client is joined to a domain.

The following simple example shows how to use the DomainAcquirer class to implement a Join Domain request on first launch of the application.

Guid c_ServiceId = new Guid("{deb47f00-8a3b-416d-9b1e-5d55fd023044}");
Uri c_DomainServerUrl = new Uri("http://domainserver.contoso.com/rmsdk/rightsmanager.asmx");
Uri c_LicenseServerUrl = new Uri("http://licenseserver.contaso.com/rmsdk/rightsmanager.asmx");

public void acquirer_JoinDomainCompleted(object sender, DomainOperationCompletedEventArgs e)
{
    if (e.Error != null)
    {
        // Standard error handling may include logging the error, 
        // retrying, or reporting failure to the user
        // e.CustomData may have additional information depending on 
        // the type of error is reported in e.Message    
    }
    else if (e.Cancelled)
    {
        // Standard cancellation handling
    }
    else
    {
        // Update the ISO store that we are joined to the domain
        // The application may want to store e.AccountId
    }
}

public void JoinDomainOnFirstUse()
{
    if (false == IsJoinedToDomain())
    {
        string friendlyName = PromptUserForClientFriendlyName();
        DomainAcquirer acquirer = new DomainAcquirer();
        acquirer.JoinDomainCompleted +=new 
            EventHandler<JoinDomainCompletedEventArgs>(
            acquirer_JoinDomainCompleted);

        acquirer.JoinDomainAsync(c_ServiceId, 
                                 Guid.Empty, 
                                 c_DomainServerUrl,
                                 friendlyName);
    }
}

You may want to provide functionality to unregister clients by allowing users to go to an account properties page. For example, you can offer an "Unregister this client" button for each device that is currently on the domain and an "Add new client" button to join other devices to the domain. If the user unregisters the current client, a Leave Domain operation is executed to remove the domain keys from the client's persistent license store. In this way, you control the number of clients that can play back controlled content, and the user controls which clients those are.

But what if the user removes a client (client x) from the domain while accessing the online account properties page from another client (client y)? Because client x is disconnected from the Internet at the time of its removal from the domain, the domain license in the persistent license store of client x is not notified of the removal, and the content can still be played on client x.

Many services have strict business rules to regulate such un-registrations. For example, they might limit the number of devices that can be unregistered in this way, require calling customer service to perform a un-registration, or apply fraud detection logic. Therefore, performing a Leave Domain is the preferred way to remove a client from the domain. The logic in the following example shows how the "Unregister this client" button might be implemented.

public void RemoveClientFromAccountButton_OnClick(object sender,
                                                  RoutedEventArgs e)
{
    //
    // The service may want to prompt the user with a "Are you sure?"
    // prompt before removing the client as it will disable media 
    // playback of any domain bound content.
    // 
    // The service will want to look up the currently logged in user’s 
    // account identifier from the ISO store.  The accountId parameter
    // is strictly required, and it is the responsibility of the
    // service to ensure that is is available at this point.
    //
    Guid m_AccountId = accountId;

    DomainAcquirer acquirer = new myDomainAcquirer();

    acquirer.LeaveDomainCompleted += new
        EventHandler<LeaveDomainCompletedEventArgs>(
        acquirer_LeaveDomainCompleted);

    acquirer.LeaveDomainAsync(c_ServiceId,
                              m_AccountId,
                              c_DomainServerUrl);
}

public void acquirer_LeaveDomainCompleted(object sender, DomainOperationCompletedEventArgs e)
{
    if (e.Error != null)
    {
        // Error handling may include logging the error, retrying, or 
        // reporting failure to the user e.CustomData may have 
        // additional information depending on the type of error is 
        // reported in e.Message
    }
    else if (e.Cancelled)
    {
        // Handle cancel
    }
    else
    {
        // Update the ISO store that we left the domain.  Likely means 
        // cleaning up the domain object for the given AccountId.
    }
}

Note   LeaveDomainAsync can fail (perhaps the client is not connected to the internet) but the client will still be removed from the domain. In this case the client thinks that they are not part of a domain yet a service might still think that the client is part of a domain. The service must provide a way to reconcile this mismatch.

The License Acquisition code, whether acquired through the MediaElement or by using the LicenseAcquirer directly, understands the RenewDomainException and DomainRequiredException errors (see Error Handling earlier in this article) that can be sent back from the license server. If the client receives one of these errors, it tries to use a DomainAcquirer (either a default instance or a user-configured one) to do a Join Domain operation using the parameters supplied in the domain error messages. The logic in the following example shows how little needs to be done at the API level to take advantage of this functionality:

public void RenewDomain()
{

    LicenseAcquirer myLicenseAcquirer = new LicenseAcquirer();
    myLicenseAcquirer.DomainAcquirer = new myDomainAcquirer();

    mediaElement.LicenseAcquirer = myLicenseAcquirer;
    mediaElement.LicenseAcquirer.LicenseServerUriOverride =
        c_LicenseServerUrl;
    mediaElement.Source = new
        Uri("https://contoso.com/content.wmv");


    //
    //  If the license server decides that the client does not have a 
    //  domain membership, the domain membership is out of date, 
    //  then a DomainRequiredException or RenewDomainException respectively 
    //  will be thrown and the client will send back a response containing
    //  the necessary information (url, serviceid, accountid, etc) to 
    //  send to the domain server.  The license acquisition pipeline 
    //  would treat this somewhat like an Indiv message in that
    //  it would do the join domain and then restart the license 
    //  acquisition.
    //
    //  Note that a customized DomainAcquirer was provided so the 
    //  OnJoinDomain method will be called to allow 
    //  authentication information to be provided with the Join Domain 
    //  request.
    //
    mediaElement.Play();
}

3.4 Rentals and Subscriptions

Enabling rental, subscriptions, or both is more complex than simply purchasing content because you need to build in more complex LicenseServer logic for license management. For example, if users download content that they are renting, you need to specify in the license when the license expires and under what conditions. The license might expire 24 hours after it is initially played or in 30 days after it is downloaded, whichever occurs first.

Rental and subscription agreements are stored in the licenses on the user’s persistent license store. Before playing content, the correct license on the persistent license store needs to be located and validated. Before going into how licenses are iterated through, let’s talk about different types of licenses and how they are chained together to enable certain scenarios.

3.5 Root Licenses, Leaf Licenses, and License Chains

A license is a data file that holds a decryption key for an asset (another license or a piece of content). It also contains DRM rights and restrictions that define how the asset that it gives access to can be used. Licenses come in three varieties:

• Simple License: A PlayReady License that is delivered from an application that is built by using the PlayReady Server SDK that contains rights and restrictions along with a key for the associated piece of content.

• Root License: A license that controls one or more leaf licenses. The leaf licenses control playback of specific pieces of content while the root license controls all of them. For example, in a subscription model, the root license may have an expiration date while the leaf licenses do not. When the root license expires, the leaf licenses are unusable until a new root license is acquired.

• Leaf License: A simple license that is dependent on a root license.

When you have leaf licenses controlled by a single root license, these licenses are said to be "chained." The following diagram shows how this looks conceptually:

Let’s say that the user has a subscription and has downloaded several videos to play back later offline . For each video, there is a leaf license that specifies the allowable usage for that video. In this case, let’s assume that the leaf license says that the user can play the video anytime. However, PlayReady ensures that there is a valid root license before allowing playback. If the root license has expired (perhaps because users allowed their subscriptions to expire), the leaf license, does not allow playback. In this way, the root license can be used to control the entire subscription (all the leaf licenses on the user’s device).

Note:
A leaf license can have more than one root license. In this case, at least one root license needs to be valid for playback to occur. In addition, a leaf license can exist without a root license.

3.6 Enumerating Through Licenses

You can check whether a license or license chain has expired by iterating through all the licenses (MediaLicense objects) on the persistent license store. If any licenses need to be updated, you can add logic to attempt to connect to the licensing server and make necessary updates, prompt the user for payment, and so on.

The following example shows how to check whether a subscription license needs to be renewed. Note that the user needs to be running Silverlight out of browser and elevated trust for license enumeration to be possible.

private void CheckSubscriptionRootForRenewal(Guid parentKeyId,
                                             Uri licenseServerUrl)
{

    DateTimeOffset renewalDate = DateTimeOffset.Now.AddDays(5);

    // Query the licensemanager to see if we have a usable root license
    IEnumerable<MediaLicense> myLicenses = LicenseManagement.SelectLicenses(parentKeyId);

    bool renewRoot = true;

    foreach (MediaLicense ML in myLicenses)
    {
        // If the license expires within the next 5 days,
        // renew the subscribtion by requesting a new root license.
        if ((ML.Usable) &&
            (ML.ExpirationDate > renewalDate))
        {
            renewRoot = false;
            break;
        }

    }

    if (renewRoot)
    {
        LicenseAcquirer acquirer = new LicenseAcquirer();
        acquirer.LicenseServerUriOverride = licenseServerUrl;
        acquirer.AcquireLicenseCompleted += new EventHandler<AcquireLicenseCompletedEventArgs>(acquirer_Completed);
        acquirer.AcquireLicenseAsync(parentKeyId, ContentKeyType.Aes128Bit, Guid.Empty);
    }

In this example, you are iterating through all the MediaLicense instances in the persistent license store. A MediaLicense instance could be any of the following:

• A license chain (leaf plus root)

• Single simple license

• Single leaf license (root does not exist)

• Single root license (root is queried directly)

The following function could be used to filter the list of content shown to the user in a list of possible playback choices, especially if the user is offline and cannot get new licenses. It could also be used to decide whether to get a license before going offline. For a subscription customer, the CheckSubscriptionRootForRenewal function (from the previous example) should be called first if the user is online.

public bool IsUsableLicenseAvailableForContent(System.IO.Stream contentFile)
{
    bool returnValue = false;

    // SelectLicenses works only if the user is running the Silverlight application offline
    // *and* elevated trust.
    IEnumerable<MediaLicense> myLicenses = LicenseManagement.SelectLicenses(contentFile);


    foreach (MediaLicense ML in myLicenses)
    {
        if (ML.Usable)
        {
            returnValue = true;
            break;
        }
    }

    return returnValue;
}

4.1 Output Protection Basics

Output protection contains five key parts: license policy data, a policy manager, a secured and compliant driver, an encrypted channel from an output port, and a compliant output device.

Policy Data

Policy Manager

Secured and Compliant Drivers

A Secured and Encrypted Channel

A Secured Output

4.2 Silverlight Support for Output Protection

The Silverlight runtime supports output protection levels contained in the optional Output Protection Level Restriction Object, Analog Video Output Configuration Restriction Object, and the Digital Audio Output Configuration Restriction Object as defined in section 4.2.2 of the PlayReady XMR specification. (The PlayReady XMR specification can be found in the documentation pack that comes with PlayReady.)

Note that the allowed values for output protection levels that can be set by a licensing server are governed by the PlayReady Compliance rules. For more information about output protection, see the PlayReady Compliance Rules.

Silverlight allows playback of content with Output Protection policies only on output connectors as specified in the PlayReady Compliance Rules. For more information about output connector terms specified in the PlayReady Compliance Rules, see Defined Terms for PlayReady Compliance and Robustness Rules.

Output Protection in Silverlight 5

Output Protection in Silverlight 4

Mixed Capabilities

Key Rotation

COPP and OPM Driver considerations

Output Protection-Related API

Silverlight MediaFailed Error Messages

4.3 Application-Restricted Media

Application-restricted media is a new feature in Silverlight 5 that enables content providers to ensure their content under DRM is consumed only by Silverlight applications they authorize. This protection is particularly useful for media that contains revenue-generating ad content.

To enable application-restricted media you must sign your application using an Authenticode x.509 certificate, just like you would to create a trusted Silverlight application. For more information, see Trusted Applications.

Note:
The Silverlight application consuming the content does not have to be a trusted application.

There are two ways that you can sign your application. You can use the SignTool.exe command-line tool or use the signing capabilities in Visual Studio.

The following shows an example command of how to sign your application using SignTool.exe:

signtool sign /v /f certificateFile.pfx fileToSign

To sign your application using Visual Studio, open the project properties for your application. On the Signing tab, specify the settings to sign your application.

See Also

Concepts