How to troubleshoot verification problems with applications that you develop by using the Windows Rights Management Services (RMS) Software Development Kit (SDK) (832962)


The information in this article applies to:

  • Microsoft Windows Rights Management Services (RMS) for Windows Server 2003

IN THIS ARTICLE

SUMMARY

This article helps you troubleshoot verification problems for applications that you develop by using the Windows Rights Management Services (RMS) Software Development Kit (SDK). This article also contains information about how to perform some common tasks that involve RMS.

The verification process makes sure that an application can participate in an RMS system. You complete the verification process by means of completing the activation process, the provisioning process, and the enrollment process. If the application stops responding at any stage, you cannot use the application.

This article describes some of the common problems that you may experience during verification. For each problem, a resolution and best practices are described. Additionally, the article contains general information about how to perform some common tasks that involve RMS.
back to the top

MORE INFORMATION

This section describes the problems that you might experience. After each problem, a resolution is described.

The RMS client does not activate

Problem description

The RMS client does not activate.

Resolution

Activation is typically unsuccessful because incorrect RMS data exists in the Microsoft Active Directory directory service. To resolve this problem, use the RMS Administration Web pages to remove the RMS service connection point (SCP) entry from Active Directory, and then reregister the RMS SCP. If the problem occurs again, remove all the computer accounts in Active Directory, and then repopulate these accounts.

Note To use the RMS Administration Web pages as described earlier, you must have the credentials of an enterprise administrator.

Best practice

Develop and test RMS applications in a dedicated domain. In a dedicated environment, you have a complete RMS system in place, and you do not risk the infrastructure of your organization.
back to the top

You activate the RMS client in the wrong hierarchy

Problem description

You may unintentionally activate an RMS server in the wrong hierarchy. For example, instead of activating the server in the PreProduction hierarchy for development and testing, you activate the server in the Production hierarchy.

Resolution

You cannot unregister an RMS server that is enrolled in a hierarchy. Therefore, you must unprovision the RMS service and then reprovision the service in the correct hierarchy.

Note If the RMS service is running, decommission the service to save all protected content, and then unprovision the service. If you do not perform this action, the content becomes inaccessible. For more information about how to set up decommissioning, see the RMS Help documentation.

Best practice

Microsoft provides the PreProduction hierarchy specifically for application developers. For RMS to use this hierarchy during provisioning, set the following registry entry to 0e3d9bb8-b765-4a68-a329-51548685fed3:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DRMS\1.0\UddiProvider


For RMS to use the Production hierarchy during provisioning, you must remove this registry entry.

Note Before you permit clients to use your RMS server to protect content, verify that the server is in the correct hierarchy.

back to the top

An RMS server does not provision

Problem description

An RMS server does not provision.

Resolution

Provisioning is the process that connects the RMS Web services to other infrastructure components. Provisioning also activates and enrolls the RMS server with the activation service. Provisioning may not succeed for various reasons.

To resolve this problem, identify the specific cause of failure, and then perform the appropriate actions. To identify the specific cause of failure, use the following checklist:
  • Access to the Internet
    Verify that the RMS server can access the Internet. During provisioning, RMS connects to the Microsoft Activation Service to download the root server's licensor certificate. This certificate is the basis of the rest of the licenses and the certificates that the RMS server distributes. If the RMS server cannot retrieve this certificate, provisioning will fail. If Web browsers can access the Internet but provisioning still fails, use a network activity capture utility to capture information about all network traffic from the RMS server. Use this information to make sure that the provisioning service can successfully access the Internet.
  • Access to the database server
    Verify that the RMS server can access the database server. If you selected a local database during provisioning, select a remote database instead, and then specify the local database name so that the RMS service performs a callback to the local host.
  • Appropriate permissions
    Verify that the RMS Service group has the appropriate permissions on the database application: read database permissions; write database permissions; and create database permissions.
  • Members of the correct domain
    Verify that both the database server and the RMS service account are members of the same Active Directory domain as the RMS server. If you cannot implement this Active Directory structure, make sure that the database server is in the same Active Directory forest as the RMS server.
  • Access control permissions
    Verify that the RMS Service group has complete access control permissions on the RMS server. If you harden your server, permissions may not receive as high a level of credentials as you originally configured. Microsoft recommends that you neither harden RMS servers nor modify the default file system permissions.
  • User permissions
    Verify that the User who is logged in to the RMS server during provisioning has sufficient permissions. Members of the Domain Administrator group have this level of permissions.
back to the top

You activate the RMS client in the wrong hierarchy

Problem description

You may unintentionally activate the RMS client in the wrong hierarchy.

Resolution

The RMS lockbox can move between hierarchies without becoming invalidated. However, if you obtain an RMS account certificate from the wrong hierarchy, the User's RMS license store is invalid. The User's RMS license store is located in the following folder:

%USERPROFILE%\Local Settings\Application Data\Microsoft\DRM

To resolve this problem, follow these steps:
  1. Remove all the files from the \DRM folder that is listed earlier.
  2. Download and activate a new RMS account certificate.
  3. Reactivate any licenses that you downloaded previously.

Best practice

To verify that you activate a computer in the correct hierarchy, use the ActMachine.exe executable program. By using this program, you activate the computer and log the computer activation so that you can verify where the computer made the activation request. To do this, type the following command at the command prompt:

actmachine.exe /l

back to the top

You cannot create a manifest for your application

Problem description

You cannot create a manifest for your application.

Resolution

To create a manifest, follow these steps:
  1. Create a manifest configuration file. This file is a text file that specifies all the manifest details.
  2. Run the GenManifest tool that is included with the RMS client SDK.
Note the following about the GenManifest tool:
  • To use the GenManifest tool, you must have a key pair and a manifest chain that contains your public key and that is signed by a root of trust (PreProduction or Production).
  • The GenManifest tool is located in the /bin subfolder of the folder where you install the RMS client SDK.
  • The GenManifest tool includes a Readme.txt file that explains the basic details of the tool, sample command-line syntax, and sample input file syntax.
back to the top

Your sample application does not run

Problem description

Your sample application may not run.

Resolution

Verify that the manifest file has a valid structure and a valid name. Additionally, verify that the manifest file exists in the same folder as the sample application. Microsoft recommends that you also review the information in the Errorcodes.h file to determine whether any one of the error conditions applies to your application.back to the top

You have to determine the e-mail address that a User uses to download an RMS account certificate

Problem description

If a User has multiple e-mail addresses, you have to determine the specific e-mail address that the User uses to download the RMS account certificate.

Resolution

RMS stores account certificates and other RMS certificates in the following folder:

%USERPROFILE%\Local Settings\Application Data\Microsoft\DRM

RMS account certificates are identified by the three-letter prefix, GIC, that comes in front of a User's e-mail address.

Best practice

Verify that each User has an e-mail address that is associated with the corresponding Active Directory user object. If a User does not have an e-mail address that is associated with the corresponding Active Directory user object, the User cannot download an RMS account certificate.back to the top

You want to review RMS error logs

Problem description

You have to review error logs that are related to RMS

Resolution

An RMS server stores error logs in both the Windows event log and the RMS logging database. However, in this version of the RMS client, you cannot log client errors that occur locally. View the error logs in the appropriate location as follows:
  • Domain controller errors are stored in the Windows event log.
  • Client errors that are related to a request to the RMS server are stored in the RMS logging database.

Best practice

Download the RMS toolkit to help you track errors. This toolkit includes a tool to help troubleshoot client errors and a tool to help you query data from the RMS database.

back to the top

REFERENCES

For more information, visit the following Microsoft Developer Network (MSDN) Web site:

Windows Rights Management Services Technology Documentation
http://msdn.microsoft.com/library/en-us/dnanchor/html/rm_sdks_overview.asp

back to the top
Modification Type:MajorLast Reviewed:12/17/2003
Keywords:kbDownload kbTrusts kbDatabase kbCertServices kbService kbServer kbClient kbdomain kbenv kbActiveDirectory kbSDK kbtshoot kbinfo KB832962 kbAudDeveloper
©2003 Microsoft Corporation. All rights reserved.