This documentation is archived and is not being maintained.

Custom IRM Protectors

Windows SharePoint Services 3

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Using the extensible Information Rights Management (IRM) architecture in Windows SharePoint Services, you can create custom rights-management protectors that convert custom files types to rights-management formats when the user downloads them, and then convert those files back to nonencrypted file formats when the user uploads them for storage in the document library.

Each IRM protector must be registered on every front-end Web server, and is made available to every document library in the farm. When you register the IRM protector, you specify which file types the protector can convert to and from rights-managed versions. A specific file type can only be associated with one IRM protector, but a given IRM protector can be associated with multiple file types.

For a file type to be rights-managed, a protector associated with that file type must be installed and registered with Windows SharePoint Services.

If you enable IRM on a document library, then all file types for which there are IRM protectors enabled are rights-managed.

Creating a custom IRM protector for certain file types enables developers to control the location of the protected content, issuance license (IL), and end-user license (EUL) within the protected version of the file, and vary the format of the protected document based on file type. In addition, developers can specify a document template to be used as the basis for the protected document. For example, suppose you had a file type that was now rights-protected in the current client application, but had not been rights-protected in previous versions of that client application. You would want to provide a generic message that could be opened in previous versions of the client application, stating that the document contents are rights-managed and cannot be displayed. You could construct your custom IRM protector so that, in protecting a document, it generates a generic "wrapper" document, with the protected content, IL, and EULs stored inside it. The wrapper document gets loaded into previous versions of the client application, displaying the message informing the user of the reason why the rights-managed content cannot be accessed.

You can create two types of IRM protectors that use the IRM framework in Windows SharePoint Services: integrated protectors and autonomous protectors.

Integrated protectors rely on Windows SharePoint Services for access to the Windows RMS platform for generating protected versions of files, and for removing protection from rights-managed files. Autonomous protectors, on the other hand, must configure and execute the entire rights-management process by themselves. Autonomous protectors may access Windows RMS platform directly, or employ some other rights-management platform.

In general, create an integrated protector if the issuance license (IL) provided by Windows RMS is sufficient for your purposes. If it is not, creating an autonomous protector gives you the ability to construct your own IL as necessary.

Create an integrated protector if you want Windows SharePoint Services to automatically create Windows RMS metadata associated with protected content. When calling an integrated protector, Windows SharePoint Services creates an issuance license (IL), functions for encrypting and decrypting the document’s content, and other metadata associated with a Windows RMS managed object. In this case, the protector acts as a file-format-specific constructor of rights-managed documents. The integrated protector does not need to know which rights the user has to the requested file, or the keys that were used to encrypt the file. The integrated protector merely consumes the rights-management information given to it. Using integrated protectors requires that there is a Windows RMS-aware client application capable of viewing the rights-managed content.

Create an autonomous protector if you want the protector to have total control over how the protected files are rights-managed. The autonomous protector has full control over the rights-management process, and can employ any rights-management platform. Unlike the process with an integrated protector, when Windows SharePoint Services invokes an autonomous protector, it passes the specific rights that the user has to the document. Based upon these rights, an autonomous protector is responsible for generating keys for the document and creating rights-managed metadata in the correct format.

The autonomous protector and the client application must use the same rights-management platform.

You can install both integrated and autonomous protectors in the same Windows SharePoint Services installation. However, you can only register a particular file type with a single protector.

Both types of protectors must implement the I_IrmProtector interface, described below.

Each IRM protector must be a COM component that implements the I_IrmProtector Interface. Implementing this interface guarantees that the protector provides Windows SharePoint Services with the functionality it needs to manage rights-managed documents of the specified file types, including:

  • Initializing the protector, including specifying whether the protector is integrated or autonomous.

  • Determining whether a file is already protected.

  • Set the correct language.

  • Protecting a document, including placing the appropriate rights management metadata inside the protected version.

  • Removing protection from a document, including sending the appropriate rights-management metadata to Windows SharePoint Services.

While both integrated and autonomous protectors must implement the I_IrmProtector interface, each type of protector implements the interface differently, because Windows SharePoint Services calls the two types using different methods of the interface. Windows SharePoint Services invokes integrated protectors using the I_IrmProtector.HrProtectRMS Method and I_IrmProtector.HrUnprotectRMS Method methods, while it invokes autonomous protectors using the I_IrmProtector.HrProtect Method and I_IrmProtector.HrUnprotect Method methods. This enables Windows SharePoint Services to pass the appropriate information to each type of protector:

  • For integrated protectors, this includes an I_IrmPolicyInfoRMS Class object, which represents methods and data that a custom integrated IRM protector can access to assist in the encryption and decryption of rights-managed files.

  • For autonomous protectors, this includes an I_IrmPolicyInfo Class object, which represents the rights management metadata that an autonomous IRM protector can access in order to rights-manage the files.

After you have compiled your custom IRM protector, you must register that protector with Windows SharePoint Services so that it can be made available for document libraries.

For information about registering IRM protectors, see How to: Register an IRM Protector.