Acquiring the End-User License

Article
03/13/2008

The end-user license is a license, signed by a license server, that details the rights for a particular user from a signed issuance license. It includes the content keys that allow protected content to be decrypted. The following items are required to get an end-user license:

Signed issuance license (created by the content publisher)
License storage session (created by the application)
Environment object (created previously by the application)

To acquire an end-user license

Obtain the signed issuance license for the content (which the application must locate, as described later in this section).
Create a license storage session, passing in an environment object and a library handle (created previously by DRMInitEnvironment), a client session (created previously by DRMCreateClientSession), and the issuance license string.
Call DRMAcquireLicense, which will put the end-user license into the permanent license store for you by default, or specify DRM_AL_NOPERSIST if you want to put the license into the temporary store and handle storage and management yourself.

If you do not pass a URL into this function, it will attempt to acquire an end-user license from a URL specified in the issuance license that was used to create the license storage session. An issuance license can hold multiple license acquisition URLs, but only the one marked "License-Acquisition-URL" will be used automatically by DRMAcquireLicense. If you want to use the others, you must parse the license with license-querying functions to retrieve the additional URLs, then pass them into the wszURL parameter of DRMAcquireLicense. To learn which URLs in the license are used and how to query for them, see End-User License Acquisition.
When the end-user license is acquired, it can be retrieved from the license store by using DRMEnumerateLicense. If DRM_AL_NOPERSIST was specified, the license will only be deposited in the temporary license store. The temporary license store will be destroyed when the DRMCloseSession function is called. To save the end-user license, the application must copy and save it.

The rights management system provides a storage mechanism, called the license store, for all necessary licenses and certificates that an application might use. The license store can hold licenses or certificates persistently or in temporary memory, and items can be retrieved from the license store by using DRMEnumerateLicense. For more information about license storage, see Storing and Retrieving Licenses and Certificates.

The acquired end-user license for a piece of content can be stored either by the rights management system in the license store (the default action), or by the consuming application in any location considered appropriate. Common examples include the header of the protected content, a custom license file, or a custom license server database. (In fact, rights account certificates and client licensor certificates can also be stored externally, although this is not usually done.)

One of the simplest places to store a signed issuance license is in the header of the protected file, so that the application can find the corresponding license and content. If the license and content were not physically connected, an application would have to parse a license to find a GUID or some other identifier that specifies which file it pertains to, and then find the corresponding file on the computer. After an application acquires an end-user license, it also can be stored in the header of a document.

The following example shows silent license acquisition. This example uses an event handler to notify the application after it either acquires the license or fails for some reason. The event handler code in the callback function is shown in Callback Function.

HANDLE hEULAcquired = NULL;   // Event for EUL acquisition.
hEULAcquired = CreateEvent(NULL, FALSE, FALSE, NULL);

// Request EUL.
hr = DRMAcquireLicense( 
          hLicenseStorage, // License storage session.
          0,     // Silent license acquisition.
                 // License is stored in permanent license store.
          NULL,  // Do not need RAC if acquiring silently.
          NULL,  // This parameter is reserved. It must be NULL.
          NULL,  // Custom data.
          NULL,  // Optional license acquisition URL.
          &hEULAcquired );  // Event handler for the request.
if(FAILED(hr))
{// Could not get a license. Handle error.}

// Check for time-out condition in license acquisition.
if (WAIT_OBJECT_0 != WaitForSingleObject( hEULAcquired, 60 * 1000))
{// Timed out, handle error.}

This example will deposit the license in the permanent license store. If you do not want the license persisted in the permanent store, you must specify DRM_AL_NOPERSIST, and the license will be entered into the temporary license store, which is destroyed when the license storage session is destroyed. To retrieve a license from either store, you must call DRMEnumerateLicense. For more information, see Storing and Retrieving Licenses and Certificates.

Licenses can only be acquired silently. When a license is acquired silently, acquisition proceeds automatically (although the callback function is alerted to progress) and the license can be put in the temporary or permanent license store.

Note In RMS client 1.0, licenses can also be acquired nonsilently. If a license is acquired nonsilently, it can only go into the permanent license store. Nonsilent license acquisition opens a browser window that allows a user to interact with the license server.

The end-user license is required by DRMCreateBoundLicense, which binds to a license to exercise its rights.

Share via

Acquiring the End-User License

See Also

Additional resources