Export (0) Print
Expand All
21 out of 31 rated this helpful - Rate this topic

Digital Rights Management (DRM)

Silverlight

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.

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.

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.

Shows how Silverlight DRM works conceptually.

Note 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

The user attempts to play some DRM-protected content in a Silverlight application that is stored on the distribution server (a distribution server, usually a Web server, is used to distribute your content). The Silverlight client downloads the content (or some of the content, in the case of streaming) and the header.

2. Is the User’s Computer Individualized?

Before Silverlight requests the license to decrypt the content, Silverlight must first determine whether the user’s computer has the appropriate DRM software installed. This software is called the individualized black box (IBX) and is the client component of DRM that is required before any protected content can be played. The individualization component software enables the client computer to request and use a DRM license. It also helps protect sensitive data that is used in the decryption process.

If the appropriate individualized component software is not already on the client, the client automatically requests the component from the Microsoft Individualization Service. The process of obtaining the individualized component software is called individualization. Silverlight individualizes the user's computer by sending information to the Microsoft Individualization Service. The user can block this information from being sent. For more information, see Error Handling later in this topic.

After a valid individualization component is installed, the client usually does not need to individualize again. An exception to this is if the PlayReady license server SDK (run by a third party) refuses to issue licenses to a given IBX version. If refusal occurs, the update is automatically initiated by the client.

You can detect when individualization is happening for the first time on a computer by using the MediaElement.CurrentState property. For more information, see Detecting DRM State.

3. Silverlight Requests License

When valid individualization component software exists on the client, it is ready to play DRM. When the user initiates playback of the protected content for the first time, the Silverlight client contacts the PlayReady License Server to obtain a license (the License Server is controlled by you or your service provider). If the License Server approves the request, it issues a license that is used by the client to decrypt the particular media file. The content can then be played.

4. Client Needs to Join Domain? (Optional)

Managing the computers on which a user can play back DRM-protected content is called "Domain Management." Managing domains is optional, but is mentioned here because it can be useful in both online and offline scenarios. The functionality that is 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.

If a computer has a domain-bound license for the content, any computer on the domain can consume Microsoft PlayReady-protected content that is acquired by any other computer in the domain. The user may easily add or remove computers from the domain, as long as the total number of computers in the domain does not exceed the limit defined by the service. Domain management is facilitated through a PlayReady domain server (domain controller server), which you provide. For more information, see domains later in this article.

5. Copy License to Persistent Licence Store (Optional)

The ability to store a license was added in the Silverlight 4 release. The license server can decide to either issue a license that is "use once" or one that is persisted on the client. Licenses persisted on the client are stored in a persistent license store, which is created on the client during individualization. Storing a license on a user’s client is particularly useful in offline scenarios. For more information, see Silverlight DRM Offline Scenarios.

6. Play Back Content

If the license that is used to play back the content is valid, playback commences.

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 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 Note:

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

Note 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).

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.

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 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.

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

Silverlight DRM diagram.

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).

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 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.

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).

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("http://contoso.com/myLicenseServer.asmx", UriKind.Absolute);

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";
}

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.

Silverlight Configuration for DRM

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 Individualizing MediaElementState. 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 AcquiringLicense MediaElementState. 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 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 Note:

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

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("http://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("http://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());
    }
  }
}

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.

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.

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("http://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);
    }
}

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:

Shows how Silverlight DRM works conceptually.

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("http://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();
}

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.

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:

Demonstrates root and leaf licenses.

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 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.

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;
}

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 data is the data inside a license, such as a PlayReady DRM license. Licenses can contain policies which explicitly declare that content requires a specific degree and form of output protection using a series of GUIDs. Licenses can also contain policies that have a single number per output indicating a desired protection level, which must in turn be mapped to different forms and degrees of output protection.

The following table shows examples of the policies that can be requested using implicit protection level based output protection mechanisms.

Policy

Description

Unrestricted

Indicates that the content is likely of lower relative value and that it can flow anywhere.

Best Effort

Indicates that the content is of higher value and that output protection should be attempted but if it cannot be engaged, allow the content to flow anyway.

Restricted

Indicates that content is of very high value and that it should not be allowed to flow over an unsecured channel.

Disallowed

Indicates that the content should not be allowed to flow through the specified channel whether secured or unsecured.

Policy Manager

The policy manager takes data from individual licenses and communicates with a compliant driver to discover the capabilities of the driver, video card, audio card, monitor, and any devices between the monitor or speakers and the computer. Based on the requested output protection level in the license and what the hardware supports, the policy manager decides if the content should be transmitted. If the content is not allowed to be transmitted, an error is returned. If the content is allowed to flow, the policy manager determines how and over what outputs the content is transmitted.

When Silverlight is used for playback, it is the policy manager.

As a policy manager, Silverlight never communicates with audio card drivers or speakers to determine their capabilities.

Secured and Compliant Drivers

A secured and compliant video or audio driver is one that meets a content protection bar (for example, part of the Windows logo program) and that implements the correct driver interface. In the case of Silverlight output protection, the required driver interface is either COPP or OPM.

COPP

Certified Output Protection Protocol (COPP) is a driver interface that enables applications to query the protection levels on a graphics cards and the drives connected to it

COPP is available for Windows Server 2003 SP1, Windows XP SP 2, and later operating systems.

OPM

Output Protection Manager (OPM) is similar to COPP. OPM is also a driver interface which allows applications to query a graphics card and the devices connected to it for their support levels of various output protection mechanisms. OPM includes capabilities that are not supported in COOP, such as the ability to have a multi-monitor setup running in Clone mode and the ability to have a repeater between the computer and the rendering device.

OPM is available for Windows Vista, Windows Server 2008 (Media Desktop Experience needed), and later operating systems.

A Secured and Encrypted Channel

There are many technologies for communicating encrypted video frames and audio samples from the video card or audio card to a secured output. Some of the technologies are Analog Copy Protection (ACP), Content Generation Management System Analog (CGMS-A), High-bandwidth Digital Content Protection (HDCP), and DisplayPort Content Protection Protocol (DPCP) where only the HDCP and DPCP are actually capable of transmitting audio.

The previous protocols work over a large number of output ports, such as component, composite, S-video, VGA, HDMI, DVI, and DisplayPort.

If there are multiple devices in the path between the graphics card and the display there could be other devices present. Each device must support the form of output protection being used. For example, a computer could be connected to a receiver, which is connected to a television, or a computer could be connected to a KVM switch.

Various output protection technologies only work with certain ports.

The following table shows the forms of output protection that are available to specific port types.

Port Type

Form of Output Protection Available

DVI-A, MicroDVI, MiniDVI [VGA via adapter] (Analog)

DVI-D, MicroDVI, MiniDVI (Digital)

HDCP

DVI-I, MicroDVI, MiniDVI (Digital / Analog)

HDCP if configured as Digital

D-SUB [VGA] (Analog)

HDMI (Digital)

HDCP

Composite (Analog)

CGMS-A, ACP

Component (Analog)

CGMS-A, ACP

S-Video (Analog)

CGMS-A, ACP

DisplayPort / MiniDiaplyPort (Digital)

HDCP, DPCP

TOSLINK - S/PDIF Audio

SCMS

HDMI - Audio

HDCP

USB - Audio

Bluetooth - Audio

Analog Jack ( 3.5mm cable for example) - Audio

Coaxial – S/PDIF Audio

SCMS

DisplayPort - Audio

Internal Video Outputs

Most graphics cards today do not have direct composite and component outputs. To get the composite and component outputs, you would typically use an adaptor from an S-Video port.

A Secured Output

The output device must support the secure protocol being used to transmit content to it. For example, most displays today understand HDCP.

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

The following table lists the behavior in Silverlight 5 with output protection policies in a PlayReady License.

Policy

Values

Windows 7 or Windows Vista

Windows XP

Macintosh

Minimum Analog Video Output Protection Level

100

Unrestricted

Unrestricted

Unrestricted**

125

Best Effort*

Best Effort

Unrestricted**

150

Best Effort

Best Effort

Unrestricted**

200

Restricted

Restricted

Disallow

>=201

Disallow***

Disallow***

Disallow***

Minimum Uncompressed Digital Video Output Protection Level

100

Unrestricted

Unrestricted

Unrestricted**

150

Best Effort*

Best Effort*

Unrestricted**

250

Best Effort

Best Effort

Unrestricted**

300

Restricted

Restricted

Disallow

>=301

Disallow***

Disallow***

Disallow***

Minimum Compressed/Uncompressed Digital Audio Output Protection Level

100

Unrestricted

Unrestricted

Unrestricted

150

Disallow

Disallow

Disallow

200

Disallow

Disallow

Disallow

250

Disallow

Disallow

Disallow

300

Disallow

Disallow

Disallow

>=301

Disallow

Disallow

Disallow

Explicit Analog Video Output Protection

CGMS-A Output Protection IDs

all configuration values

(See PlayReady Compliance Rules)

Enforces according to PlayReady Compliance Rules

Enforces according to PlayReady Compliance Rules

Disallow

Image Constraint Token Output Protection ID

(See PlayReady Compliance Rules)

Disallow

Disallow

Disallow

AGC/Color Stripe Output Protection ID

all configuration values

(See PlayReady Compliance Rules)

Disallow

Disallow

Disallow

Explicit Digital Audio Output Protection

SCMS Output Protection ID

all configuration values

(See PlayReady Compliance Rules)

Disallow

Disallow

Disallow

  • *Playback may be allowed if output connector cannot be determined. Silverlight will evaluate all output protection policies in this case and enforce the most restrictive policy.

  • **Silverlight will evaluate all output protection policies in this case and enforce the most restrictive policy.

  • ***If connector cannot be determined, the presence of this output protection level (independent of which output protection level policy) will result in a Disallow

Output Protection in Silverlight 4

The following table lists the behavior in Silverlight 4 with output protection policies in a PlayReady License.

Policy

Values

Windows 7 or Windows Vista

Windows XP

Macintosh

Minimum Analog Video Output Protection Level

100

Unrestricted

Unrestricted

Unrestricted

150

Restricted

Restricted

Restricted3

200

Restricted

Restricted

Disallow

>=201

Restricted1

Restricted1

Restricted1

Minimum Uncompressed Digital Video Output Protection Level

100

Unrestricted

Unrestricted

Unrestricted

250

Best Effort

Best Effort

Best Effort3

270

(<=520k pixels)

Best Effort

Best Effort

Best Effort

270

(>520k pixels)

Restricted

Restricted

Disallow

300

Restricted

Restricted

Disallow

>=301

Disallow

Disallow

Disallow

Minimum Compressed Digital Video Output Protection Level

>=0

Restricted1

Restricted1

Restricted1

Minimum Compressed/Uncompressed Digital Audio Output Protection Level

100

Unrestricted

Unrestricted

Unrestricted

150

Disallow

Disallow

Disallow

200

Disallow

Disallow

Disallow

250

Disallow

Disallow

Disallow

300

Disallow

Disallow

Disallow

>=301

Restricted1

Restricted1

Restricted1

Explicit Analog Video Output Protection

CGMS-A Output Protection IDs

all configuration values

(See PlayReady Compliance Rules)

Restricted

Restricted

Same as CGMS-A2

Image Constraint Token Output Protection ID

(See PlayReady Compliance Rules)

Disallow

Disallow

Disallow

AGC/Color Stripe Output Protection ID

all configuration values

(See PlayReady Compliance Rules)

Disallow

Disallow

Disallow

Explicit Digital Audio Output Protection

SCMS Output Protection ID

all configuration values

(See PlayReady Compliance Rules)

Disallow

Disallow

Disallow

  • 1In this case, it always results in Block

  • 2Equivalent to setting the Minimum Analog Video Output Protection Level = 200

  • 3In this case, it results in Play

Mixed Capabilities

In a dual monitor setup, it is possible that one monitor is connected to an output that supports protection while the other monitor is connected to an output that does not. For example, a computer could be connected to a TV that does not support output protection and to a monitor that does support output protection. In these cases where there are mixed capabilities, both connections must conform to the requested output protection level of the license. If they do not both conform, then playback will be blocked. Output protection policy is interpreted based on the least protective port provided. The following table lists the interpretations to the four basic policies.

Policy

Interpretation

Unrestricted

No change in interpretation. The connection can be over any combination of protected or unprotected ports.

Best Effort

If one or more of the outputs cannot support the content protection, then after all the outputs have been tried (and some failed) then content is played.

Restricted

If all connections cannot engage output protection to the desired level, block content playback.

Disallowed

No change in interpretation as all content output is already blocked.

Key Rotation

Silverlight releases prior to version 5 enabled content providers to apply specific policies to encrypted content. These policies are typically associated with a single license, where the content policy and the content key are part of a single license. However, Live TV scenarios introduce new challenges on how policies and licenses are managed across the system. In those scenarios, both content keys and policies can change at any point in the stream and client applications need to enforce those policies in real time.

PlayReady 2.0 Server Technology provides support for these new Live TV scenarios and their corresponding support in the Protected Interoperable File Format (PIFF) specification. A Silverlight 5 client manages the enforcement of changing policies for the developer. No special client application code is required. Microsoft provides support for consuming PIFF content. For more information, see Smooth Streaming Client. For more information about licensing PlayReady Server Technology, see the PlayReady site.

A Silverlight 5 developer can build their own client implementation using Silverlight’s MediaStreamSource. When building your own MediaStreamSource, you need to be aware that policy changes can be triggered by the content provider or operator and the client reacts immediately to engage the output protection specified in the new license. Output protections are engaged at the time of DRM decryptor setup. If the necessary protections defined in the contents PlayReady license cannot be engaged, then the decryptor creation will fail. The error will be available in the DrmSetupDecryptorCompletedEventArgs parameter of the MediaStreamSource.DrmSetupDecryptorCompleted event.

COPP and OPM Driver considerations

Before using COPP or OPM, the graphics card's COPP or OPM certificate must be validated and then checked to ensure that it is not on a revoked list. If the certificate is either revoked or is not valid when checked, the Silverlight runtime will raise a MediaFailed event with the 6036 error code.

For more information on how to validate and check against the revocation list, see Validating the Certificate Chain.

Output Protection-Related API

You can use the following API in Silverlight to detect the output protection available on a device. You can then add this information to a license request and then determine on the server whether or not to playback content.

LicenseManagement.VideoOutputConnectors Property

Gets, from the graphics card, all of the data on connector types and what output protections Silverlight can engage for each video output.

VideoOutputConnector Class

Returned by the VideoOutputConnectors property and provides the actual data on connector types and what output protections Silverlight can engage.

VideoOutputConnectorType Enumeration

Returned by the VideoOutputConnector.ConnectorType property and defines of all of the commonly available output connector types.

Silverlight MediaFailed Error Messages

The errors for this feature will all propagate through the MediaFailed event and are all related to changes during playback.

Error Code

Notes

6030

"This content requires an output protection which cannot be enabled on this machine"

This error is raised via the MediaFailed event whenever a license contains an unsupported license protection. This error is raised before the MediaOpened event has been raised.

6031

"The integrity of the secured video output connection has been compromised or lost"

This error is raised via the MediaFailed event whenever Silverlight polls the OPM interface via GetInformation and the OPM_STATUS_LINK_LOST flag is returned.

6032

"The secured graphics connection requires renegotiation but could not be renegotiated"

This error is raised via the MediaFailed event whenever Silverlight polls the OPM interface via GetInformation and the OPM_STATUS_RENEGOTIATION_REQUIRED flag is returned.

6033

"A revoked High-Bandwidth Digital Content Protection (HDCP) device is attached to the video output"

This error is raised via the MediaFailed event whenever Silverlight polls the OPM interface via GetInformation and the OPM_STATUS_REVOKED_HDCP_DEVICE_ATTACHED flag is returned.

6034

"The graphics adapter or the driver has been tampered with."

This error will be raised via the MediaFailed event whenever Silverlight polls the OPM interface via GetInformation and the OPM_STATUS_TAMPERING_DETECTED flag is returned.

6035

"A new graphics connection was added during playback and playback was halted"

WM_DeviceChange/RegisterDeviceNotification is used to keep track of monitors being added. If a new monitor is added during playback of protected content requiring output protections and only protected content requiring output protections, the MediaFailed event is raised.

6036

"Graphics device's driver certificate is invalid."

This is raised whenever the runtime encounters a bad OPM or COPP certificate.

6037

"This content cannot be played over a remote session"

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 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.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.