Creating Revocation Lists

Article
09/21/2010

Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2

Implementing revocation requires that you deploy a revocation list, which is an XML document that uses the eXtensible Rights Markup Language (XrML), and lists the principals that should no longer have access to rights-protected content. You must create revocation lists that are time-stamped and signed appropriately by using the Revocation List Signing tool (RLsigner.exe) provided with RMS.

Important

To sign the revocation list by using RLsigner.exe, you must save the revocation list file as a unicode file.

Revocation List Example

This topic presents a complete revocation list example that shows each of the possible revocation mechanisms. You can use this example as a model to create your own revocation lists.

A revocation list is an XML file that uses the XrML language.

The BODY element contains four child elements:

ISSUEDTIME. Contains the date and time of issuance of the revocation list. RLsigner.exe inserts this element into the file; the element is provided in the example only to demonstrate the overall structure of the revocation list file.
DESCRIPTOR. Contains data that identifies the file as a revocation list.
ISSUER. Contains data that identifies the entity that issues the revocation list.
REVOCATIONLIST. Contains child REVOKE elements that specify entities that are revoked by this list.

A sample revocation list file is shown below.

Note

The ISSUEDTIME, PUBLICKEY, and SIGNATURE elements can be omitted because they are inserted or overwritten by RLsigner.exe.

<?xml version="1.0" ?>
<XrML xml:space="preserve" version="1.2">
  <BODY type="LICENSE" version="3.0">
    <ISSUEDTIME>...</ISSUEDTIME>
    <DESCRIPTOR>
      <OBJECT type="Revocation-List">
        <ID type="MS-GUID">{d6373cba-01f1-4f32-ac58-260f580af0f8}</ID>
      </OBJECT>
    </DESCRIPTOR>
<ISSUER>
      <OBJECT type="Revocation">
        <ID type="ascii-tag">External revocation authority</ID>
        <NAME>Revocation list name</NAME>
        <ADDRESS type="URL">https://somedomain.com/revocation_list_file</ADDRESS>
      </OBJECT>
      <PUBLICKEY>...</PUBLICKEY>
    </ISSUER>
  <REVOCATIONLIST>
    <REVOKE>...<\REVOKE>
    <REVOKE>...<\REVOKE>
  </REVOCATIONLIST>
</BODY>
  <SIGNATURE>...</SIGNATURE>
</XrML>

Warning

When specifying the URL in the revocation list, a UNC path is no longer support in RMS with SP1 or RMS with SP2. You must use a URL.

After you have defined the REVOKE elements, the revocation list is ready to be signed.

Using the REVOKE Element

In the example revocation list in the Revocation List Example section, each REVOKE element specifies a principal that is to be revoked. The opening tag has category and type attributes that define what is being revoked and by what identifying criterion. Different REVOKE elements have different child elements, depending on the action that is specified by the category and type attributes.

For more information about specifying REVOKE elements, see the following samples:

Revoking Principals Based on a Public Key
Revoking Certificates and Licenses Based on GUID
Revoking Certificates and Licenses Based on Hash Value
Revoking Certificates and Licenses Based on Issuer Public Key
Revoking Certificates and Licenses Based on Issuer ID
Revoking Content Based on Content ID
Revoking Certificates based on principal ID
Revoking Principals Based on Windows Live ID

Revoking Principals Based on a Public Key

This example revokes a principal based on its public key. The content of the <PUBLICKEY> tag here is from the <BODY><ISSUEDPRINCIPALS><PRINCIPAL><PUBLICKEY> node of the certificate that issued the key.

      <REVOKE category="principal" type="principal-key">
        <PUBLICKEY>
          <ALGORITHM>RSA-1024</ALGORITHM>
          <PARAMETER name="public exponent">
            <VALUE encoding="integer32">65537</VALUE>
          </PARAMETER>
          <PARAMETER name="modulus">
            <VALUE encoding="base64" size="1024">
6Jn0kEAWU+1AFWtuUmBYL8Jza8tLhUv/BCmgcq/Pc08Au3DvXkH65s+0MEyZjM+71j3F1xaXUSst+wH2FjApkY1RxgL8VAKIuEvIy9hRrvY1YhJx/0Ite5fZeg2crUFrmoQgZzaJ50FvoakA2QMgZZgxoQmwiGE0y40cEJtIlE0=
            </VALUE>
          </PARAMETER>
        </PUBLICKEY>
      </REVOKE>

Revoking Certificates and Licenses Based on GUID

This example revokes a certificate or license by its globally unique identifier (GUID). You cannot use a certificate or license with a matching GUID when this revocation list is used. The content of the <ID> tag in this example is from the <BODY><DESCRIPTOR><OBJECT><ID> node of the certificate or license that you are revoking. (You can also revoke applications through this mechanism by specifying the ID of the application manifest.)

<REVOKE category="license" type="license-id">
        <OBJECT>
          <ID type="MS-GUID">{06BCB94D-43E5-419f-B180-AA9FD321ED7A}</ID>
        </OBJECT>
      </REVOKE>

Revoking by application manifest

To revoke by application manifest, you must extract the issuer ID, issuer public key, license ID, or license hash from the application manifest. However, application manifests are base 64-encoded, so that information is not available in plain text. With the Rights Management Services Software Development Kit (SDK), a program can be developed using the DRMConstructCertificateChain, DRMDeconstructCertificateChain and DRMDecode methods to decode the application manifest and obtain the required information.

If you want to prevent a certain application’s ability to consume rights-protected content, consider using application exclusion to prohibit the RMS cluster from granting use licenses to those applications. The limitation of exclusion is that it cannot prevent someone with a valid use license from decrypting rights-protected content. For more information about application exclusion, see Excluding Applications earlier in this subject.

Revoking Certificates and Licenses Based on Hash Value

This example revokes a certificate or license by its hash. The content of the <VALUE> tag here is the SHA-1 hash of the UNICODE characters from <BODY> to </BODY>, inclusive, in the certificate or license. You can find this hash value in the <SIGNATURE> section of the certificate or license. (You can also revoke applications through this mechanism by specifying the hash of the application manifest.)

<REVOKE category="license" type="license-hash">
        <DIGEST>
          <ALGORITHM>SHA1</ALGORITHM>
          <VALUE encoding="base64" size="160">
            ABfB4mcEslVCMEZR9reACqXHCoQ=
          </VALUE>
        </DIGEST>
      </REVOKE>

Revoking by application manifest

To revoke by application manifest you must extract the issuer ID, issuer public key, license ID, or license hash from the application manifest. However, application manifests are base 64–encoded, so that information is not available in plain text. With the Rights Management Services SDK, a program can be developed using the DRMConstructCertificateChain, DRMDeconstructCertificateChain and DRMDecode methods to decode the application manifest and obtain the required information.

If you want to prevent a certain application’s ability to consume rights-protected content, consider using application exclusion to prohibit the RMS cluster from granting use licenses to those applications. The limitation of exclusion is that it cannot prevent someone with a valid use license from decrypting RMS-protected content. For more information about application exclusion, see Excluding Applications earlier in this subject.

Revoking Certificates and Licenses Based on Issuer Public Key

This example revokes all certificates and licenses that are issued by the owner of the specified public key. The content of the <PUBLICKEY> tag here is the <BODY><ISSUER><PUBLICKEY> node of the certificates or licenses that you are revoking.

<REVOKE category="license" type="issuer-key">
        <PUBLICKEY>
          <ALGORITHM>RSA-1024</ALGORITHM>
          <PARAMETER name="public exponent">
            <VALUE encoding="integer32">65537</VALUE>
          </PARAMETER>
          <PARAMETER name="modulus">
            <VALUE encoding="base64" size="1024">
AAn0kEAWU+1AFWtuUmBYL8Jza8tLhUv/BCmgcq/Pc08Au3DvXkH65s+0MEyZjM+71j3F1xaXUSst+wH2FjApkY1RxgL8VAKIuEvIy9hRrvY1YhJx/0Ite5fZeg2crUFrmoQgZzaJ50FvoakA2QMgZZgxoQmwiGE0y40cEJtIlE0=
            </VALUE>
          </PARAMETER>
        </PUBLICKEY>
      </REVOKE>

Revoking Certificates and Licenses Based on Issuer ID

This example revokes a set of certificates or licenses by the ID of the issuer. The content of the <ID> tag here is the <BODY><ISSUER><OBJECT><ID> node of the certificates or licenses that you are revoking.

      <REVOKE category="license" type="issuer-id">
        <OBJECT type="MS-DRM-Server">
          <ID type="MS-GUID">{2BE9E200-3040-41B9-8832-D4D0445EBBD6}</ID>
        </OBJECT>
      </REVOKE>

Note

When specifying the ID type, make sure no carriage return is between the globally unique identifier (GUID) and the closing tag. If a carriage return is inadvertently added, the RMS client cannot parse the revocation list.

Revoking Content Based on Content ID

This example revokes protected content by its content ID. This is the preferred method that you should use to revoke content because the content ID is the same across all use licenses that are created from a given publishing license. The value of the <OBJECT> node here can be found in the <BODY><WORK><OBJECT> node of either a publishing license or a use license for the content.

<REVOKE category="content" type="content-id">
        <OBJECT type="Microsoft Office Document">
          <ID type="MS-GUID">{8702641D-3512-4AA4-A584-84C703A5B5C0}</ID>
        </OBJECT>
      </REVOKE>

Note

Revoking principals based on Windows account

This example revokes a user or enabling principal by its Windows account. The content of the <OBJECT> element here is from the <BODY><ISSUEDPRINCIPALS><PRINCIPAL><OBJECT> node of a rights account certificate or use license.

<REVOKE category="principal" type="principal-id">
        <OBJECT type="Group-Identity">
          <ID type="Windows">{Windows account SID}</ID>
          <NAME>{E-mail address}</NAME>
        </OBJECT>
      </REVOKE>

Note

When specifying the ID type, make sure no carriage return is between the Windows account SID and the closing tag. If a carriage return is inadvertently added, the RMS client cannot parse the revocation list.

Revoking Principals Based on Windows Live ID

This example revokes a user or enabling principal by its Windows Live ID. The content of the <OBJECT> element here is from the <BODY><ISSUEDPRINCIPALS><PRINCIPAL><OBJECT> node of a rights account certificate or use license.

<REVOKE category="principal" type="principal-id">
        <OBJECT type="Group-Identity">
          <ID type="Passport">{PUID}</ID>
          <NAME>michael@contoso.com</NAME>
        </OBJECT>
      </REVOKE>

Note

When specifying the ID type, make sure no carriage return is between the principal unique identifier (PUID) and the closing tag. If a carriage return is inadvertently added, the RMS client cannot parse the revocation list.

Inserting a Signature into a Revocation List

When you finish creating a revocation list, you must insert a signature into the revocation list as described in this topic. You can then make the revocation list available to users from the URL that you specify in the associated rights policy template.

The first step for inserting a signature is to generate a key pair and key file for the revocation list by using the Strong Name tool (Sn.exe). The Sn.exe tool is included with the Microsoft .NET Framework SDK 1.1, which is available from the Microsoft Web site https://go.microsoft.com/fwlink/?LinkId=104796.

Your revocation list file must have been saved as a unicode file in order to sign it by using RLsigner.exe

To use Sn.exe both to generate a new key pair and to write that pair to a file

Create the private key. At a command prompt, type the following command, and then press ENTER:

sn -k private_key_file .snk

where private_key_file is the name of the key file.
Use Sn.exe to extract the public key from the key pair file created in Step 1 and export it to a separate file. Type the following command, and then press ENTER:

sn -p private_key_file public_key_file

where private_key_file is the name of the private key file created in Step 1 and public_key_file is the name of the file where the exported public key will be stored.
Change the extension of the private key file (created in Step 1) from .snk to .dat for use with RLsigner.exe.
Use RLsigner.exe to insert a signature into a revocation list file. This tool is included with RMS. By default, it is located in the %systemdrive%\Program Files\Windows Rights Management Services\Tools directory.

Note

RLsigner.exe does not support file names that include spaces.

Using RLsigner.exe

When you run RLsigner.exe, it first creates a signature by using the private key that is provided in the key file. It then creates an output file that is based on the revocation list file that you provided.

Important

The revocation list file must have been saved as a unicode file to use RLsigner.exe.

To use RLsigner.exe to sign the revocation list, type the following command at a command prompt:

rlsigner.exe input_file {-f key_file | -h container_name CSP} output_file

Use the following information to complete the input parameters for the command:

Parameter	Description
input_file	Name of the XrML-compliant revocation list file that you have prepared
key_file	Name of the file that contains both the public and private keys that you have generated
container_name	Name of the key container
output_file	Name of the signed revocation list file that the tool will create

Note

RLsigner.exe does not support file names that include spaces.

The following examples describe how you can use RLsigner.exe at a command prompt with different cryptographic service providers:

Example command-line syntax that uses a key file:

rlsigner.exe rl.xml -f key.dat output.xml
Example command-line syntax that uses a hardware security module:

rlsigner.exe rl.xml -h Container CSP output.xml

RLsigner.exe provides basic error and success information in its return code. The following table describes the possible return codes.

Return Code	Description
0	Success
-1	Unable to read the source file
-2	Unable to read the key file
-3	Invalid key file
-4	Invalid source file
-5	Unable to write the output file
-6	Unknown error

You may want to schedule the signing of revocation lists based on the refresh rate that you specified for your server.

You can automate the revocation list signing process by using a script. The following sample VBScript calls RLsigner.exe and writes the results to the System event log.

const EVT_SUCCESS       = 0
const EVT_ERROR         = 1
const EVT_WARNING       = 2
const EVT_INFORMATION   = 4
const EVT_AUDIT_SUCCESS = 8
const EVT_AUDIT_FAILURE = 16

Dim WshShell, oExec

Set WshShell = CreateObject( "WScript.Shell" )
Set oExec = WshShell.Exec("rlsigner.exe input_file key_file output_file")
Do While oExec.Status = 0
     WScript.Sleep 100
Loop

if WshShell.ExitCode <> 0 Then
    WshShell.LogEvent EVT_ERROR, "RLsigner failed with error """ + WshShell.ExitCode + """"
else
    WshShell.LogEvent EVT_SUCCESS, "RLsigner completed successfully"
end if

Creating Revocation Lists

Revocation List Example

Using the REVOKE Element

Revoking Principals Based on a Public Key

Revoking Certificates and Licenses Based on GUID

Revoking by application manifest

Revoking Certificates and Licenses Based on Hash Value

Revoking by application manifest

Revoking Certificates and Licenses Based on Issuer Public Key

Revoking Certificates and Licenses Based on Issuer ID

Revoking Content Based on Content ID

Revoking principals based on Windows account

Revoking Principals Based on Windows Live ID

Inserting a Signature into a Revocation List

To use Sn.exe both to generate a new key pair and to write that pair to a file

Using RLsigner.exe

Additional resources