Registering Revocation Lists

Article
03/13/2008

A revocation list contains a list of users, certificates, computers, or possibly other principals that are blocked from access to content. Not all licenses require a revocation list, but if a license requires one (or more), the list or lists must be registered by using the DRMRegisterRevocationList function before a bind can succeed. These lists are stored in the license store, and can be enumerated by using the DRMEnumerateLicense function when you want to register them. This registration is only good for the lifetime of the environment, so when an application closes and reopens (or simply opens a new environment), any required revocation lists must be reregistered. Revocation lists must be up to date, as specified by the license's revocation list refresh period.

When you acquire an end-user license by using the DRMAcquireLicense function, the AD RMS system automatically attempts to retrieve all required revocation lists (the application must still register any retrieved lists with DRMRegisterRevocationList). You will only have to manually acquire revocation lists if the existing revocation lists are out of date or missing, for some reason, or if you are reusing a stored end-user license obtained from a previous environment session. You only need to register a revocation list once per environment object, not once per license storage session or client session.

You can check to determine whether a license requires a revocation list, and if the list is valid, at several different points, but the easiest way is to attempt to bind to a license and check for E_DRM_BIND_NO_APPLICABLE_REVOCATION_LIST, rather than enumerating revocation lists.

After you have determined that you need a new revocation list for a license, there are several ways to go about acquiring a list (if one is not already available on your system) and registering it.

There are two different approaches, one simple and the other complex:

Acquire a new revocation list by using DRMAcquireAdvisories, then enumerate all revocation lists and register all of them.

This approach is simple to program because it eliminates the need to parse each license and list to find corresponding items. However, when you register all revocation lists, whether they apply to a license you intend to use or not, you add overhead by not removing stale lists from the store and by always acquiring a new list from a revocation list distribution point. The acquired list is not handed back directly to the callback function; it is deposited in the license store, from where it must be retrieved by using the DRMEnumerateLicense function.
Check for an existing revocation list before trying to acquire a new one.

This approach avoids the overhead of attempting to acquire a new license if one is already present, and it also allows an application to remove stale revocation lists. However, it is considerably more complex than the previous method. The following pseudocode shows this approach.

Enumerate revocation lists by ID (DRMEnumerateLicense with DRM_EL_REVOCATIONLIST_LID flag) { if (Enumerated Revocation List ID == Content ID) { DRMRegisterRevocationList() the retrieved list DRMCreateBoundLicense to attempt bind if (DRMCreateBoundLicense returns E_DRM_BIND_NO_APPLICABLE_REVOCATION_LIST) { // Delete this license. } else if (succeeded) { // The bind is good. Jump out and continue with the program. } else (some other error) { // Handle error and quit loop. } }
```
//  Obtain the next license.
```
}

If no licenses worked, get new license with DRMAcquireAdvisories DRMEnumerateLicense to find the license DRMBindLicense to bind to it. If bind fails, this license is revoked.

A revocation list can be tied to several things, including secure stores, group identification certificates, or client licensor certificates. The end-user license allows a content publisher to specify where a consumer must obtain a revocation list and the validity period of the list. Revocation lists are stored in the license store, and although the DRMEnumerateLicense function allows an application to search through the license store for a particular revocation list to ensure that it exists and is up to date, the easiest way to determine whether content has a valid revocation list is to attempt to bind to the license and trap for secure store errors.

The following example shows a basic bind, and does not show the revocation list retrieval or registration. The code uses an event handler to notify the application when it has acquired the revocation list. The event handler code in the callback function is shown in Callback Function.

// First attempt to bind.
hr = DRMCreateBoundLicense( 
    hEnv,  // Environment object.
    oParams,  // Rights and other stuff.
    wszEUL,   // EUL.
    &hBoundLicense, // Bound license.
    NULL );  // Error log.

// If the attempt to bind fails because of a 
// missing revocation list, then update the list.
if (hr == E_DRM_BIND_NO_APPLICABLE_REVOCATION_LIST)
{
    HANDLE hRevLstEvent = NULL; // Holds event object to wait for
                            // asynchronous function call.
    hr = DRMAcquireAdvisories( 
        hLicenseStorageSession,
        wszEUL,
        NULL,   // Let the license suggest the URL.
        &hRevLstEvent);   // Waits for function.

    if(FAILED(hr))
    {
        // Could not get a revocation list. Handle error.
    }

    if (WAIT_OBJECT_0 != WaitForSingleObject(hRevLstEvent, 60 * 1000))
    {
        // More than 60 seconds may be a problem. Handle error.
    }
}
else 
{
    // Handle some other errors.
}

In the example, DRMAcquireAdvisories attempts to get a revocation list when no valid list is found in the license store. After DRMAcquireAdvisories returns successfully, call DRMCreateBoundLicense again. If the new revocation list is replacing an out of date version, the older version should be deleted by calling the DRMDeleteLicense function.

For an example of a revocation list, see Sample Revocation List. Do not try to use this list because the signature is not valid, and the entries are for example purposes only. For more information about how to build revocation lists, see the Active Directory Rights Management Services deployment guide, which comes with Rights Management Services.

Share via

Registering Revocation Lists

See Also

Additional resources