Testing your rights-enabled application

Article
05/24/2016

This topic describes the steps you need to complete to test your Rights Management Services SDK 2.1 rights-enabled application.

To publish and consume protected content, an Rights Management Services (RMS) application makes use of several different types of certificates and licenses, each of which consists of a certificate chain that leads back ultimately to a Microsoft certification authority. Microsoft provides the following hierarchies:

The Pre-production hierarchy can be used to develop and test applications.
The Production hierarchy must be used by released applications

We recommend that you use the Pre-production hierarchy when developing an application. By doing so, you can work without signing a Production License Agreement with Microsoft.

Important It is a recommended best practice to test your RMS SDK 2.1 application first with the RMS pre-production environment against an RMS Server. Then, should you want your customer to have the ability to use your application with the Azure RMS Service, move to testing with that environment. For more information see, Enable your service application to work with cloud based RMS.

Prerequisites

An RMS SDK 2.1 development environment setup. For more information, see Setting up the pre-production development environment.
For an example application, see IPCHelloWorld - an example application.

Instructions

Step 1:

Create and build a rights-enabled application. See the above Prerequisites section for options.

Step 2: Generate an application manifest using the pre-production certificate chain

You must generate a manifest for your application before running it.

Note If your application uses Server API Mode (IPC_API_MODE_SERVER), you are not required to use an application manifest. You can test your application against a production AD RMS server and you are not required to obtain a production license when switching to production environment. For more information on server mode applications, see Application types.

This process is also known as signing your application. You can generate the manifest using either a production certificate chain or the pre-production certificate chain that is installed with the SDK. We recommend that you use the pre-production certificate chain during development.

For more information about keys and certificate chains, see Understanding certificate chains.

For information about how to sign an application with a production certificate chain, see Switching to the production environment.

To generate the application manifest using the pre-production certificate chain, perform these steps on your development computer:

Copy the following files from their installation directories to the same folder as your application.

%MSIPCSdkDir%\Tools\Genmanifest.exe

%MSIPCSdkDir%\bin\Isvtier5appsigningprivkey.dat

%MSIPCSdkDir%\bin\Isvtier5appsigningpubkey.dat

%MSIPCSdkDir%\bin\Isvtier5appsignsdk_client.xml

%MSIPCSdkDir%\bin\YourAppName.isv.mcf
In your application folder, rename the manifest configuration file, YourAppName.isv.mcf, to the name of your application with the .mcf file name extension appended. For example if your application is named MyApp.exe, rename YourAppName.isv.mcf to MyApp.exe.mcf.
Use a text editor to add your application to the manifest configuration file. To do this, replace the <YourAppName>.exe place holder text in the module list inside your .mcf file with the name of your application; for example, MyApp.exe.

The signing process will generate an error if the .mcf file is used without modification.
Run Genmanifest.exe to generate the application manifest. This is also known as signing your application. The output of this operation should be a .man file. For example, if your application is named MyApp.exe and your manifest configuration file is named MyApp.exe.mcf, run the following command:

genmanifest.exe -chain isvtier5appsignsdk_client.xml MyApp.exe.mcf MyApp.exe.man

Step 3: Run your application

You can run your application from any directory, but the application manifest (MyApp.exe.man) must be in the same directory as the executable (MyApp.exe).

Using the RMS 1-Box Environment

If you are using the RMS 1-box environment to test your application, copy your application executable and the application manifest to any directory on the 1-box environment and then run your application.

For information about the RMS 1-box environment, see Set up the test environment.
Using a pre-production Server configuration

If you are testing your application against an RMS server that is configured for pre-production, make sure that you have configured the Active Directory Rights Management Services Client 2.1 on the computer where the application will be running; for example, on your development computer. Then make sure that both the application executable and the application manifest are located in the same directory on that computer and run your application.

For information about how to configure the client on your computer, see Configure the client. For information about installing an RMS server, see Install and configure the server.