Share via

Building a Consuming Application

  • Article

An application must follow a particular order of steps to consume Active Directory Rights Management Services (AD RMS)–protected content.

Many functions in AD RMS depend on objects that are created or obtained by other functions, so although the order of tasks is not rigid, you must be aware of what functions must execute before other functions to prepare the necessary objects. A good example of this is obtaining licenses or certificates, which takes place several different times in an application.

Some steps, such as rights processing or license querying, can be quite complex and typically must be custom-designed for an application. The documentation describes the basic process, illustrates it with an example, and gives some information about the variations that an application might need to address.

The examples do not cover error checking exhaustively. An application designer is expected to trap generic errors that are appropriate to a step (such as E_DRM_ENV_CANNOT_LOAD when attempting to create an environment handle) and handle them appropriately.

Overview of the Content Consumption Pathway

The following diagram shows the basic content consumption pathway. The process shows general steps in a consumption pathway after the application determines that the content is protected by Active Directory Rights Management Services (AD RMS) and has located the signed issuance license for that content. For more information, see the topics listed later in this topic.

Path for a consuming application

The diagram shows the following details:

  1. Create a client session.

  2. Determine whether the computer and user are activated and, if not, activate them.

  3. Obtain the lockbox, machine certificate, and the manifest for necessary libraries, and create a secure environment object required by other functions.

  4. Obtain an end-user license (EUL) and retrieve the content ID from the license.

    • Use the signed issuance license associated with the content to acquire a new EUL or obtain an existing license from the content file or from the license store. Call DRMDeconstructCertificateChain to retrieve the EUL from the license chain.

    • To retrieve the content ID from the EUL, perform the following steps:

  5. Submit the end-user license to the rights management system's temporary or permanent license store, which holds certificates and licenses for content access. The temporary license store is destroyed when the DRMCloseSession function is called, whereas the permanent license store can be used to hold licenses in persistent memory. An enabling principal must also be created for the next step.

  6. Bind to the license, which means that the application requests the rights to exercise. The rights management system then checks that the current user is granted those rights and returns a queried version of the XrML license that contains only those rights requested.

  7. Use the bound license to create an enabling bits AD RMS decrypting object, which is used to decrypt the AD RMS-protected content. Content is decrypted as needed. If your user interface displays the decrypted content, we recommend that you use the DRMRegisterContent function to increase user interface security by blocking print screen, among other features.

The following topics describe the steps involved in creating a consuming application:

The following topics contain additional important information for an AD RMS-enabled consuming application:

For information about building an AD RMS-enabled publishing application, see Building a Publishing Application.

A compilable C++ sample comes with the AD RMS SDK. To build and run a working AD RMS-enabled publishing and consuming application, see the samples installed in the \Samples folder where your AD RMS SDK was installed.

Send comments about this topic to Microsoft

Build date: 3/13/2008