Custom IRM Protectors
Applies to: SharePoint Foundation 2010
Using the extensible Information Rights Management (IRM) architecture in Microsoft SharePoint Foundation 2010, you can create custom rights-management protectors that convert custom file types to rights-management formats when the user downloads them, and that 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 be associated with only 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 SharePoint Foundation.
If you enable IRM on a document library, 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 to vary the format of the protected document based on file type. Developers can also specify a document template to be used as the basis for the protected document. For example, suppose you have a file type that is rights-protected in the current client application, but that was not rights-protected in previous versions of that client application. You want to provide a generic message that can be opened in previous versions of the client application, stating that the document contents are rights-managed and cannot be displayed. You can 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.
Integrated and Autonomous Protectors
You can create two types of IRM protectors that use the IRM framework in SharePoint Foundation: integrated protectors and autonomous protectors.
Integrated protectors rely on SharePoint Foundation for access to the Windows RMS platform for generating protected versions of files, and for removing protection from rights-managed files. Autonomous protectors must configure and execute the entire rights-management process. Autonomous protectors may access the Windows RMS platform directly, or may use some other rights-management platform.
In general, you 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.
Create an integrated protector if you want SharePoint Foundation to automatically create Windows RMS metadata associated with protected content. When calling an integrated protector, SharePoint Foundation creates an issuance license (IL), functions for encrypting and decrypting the document 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 use any rights-management platform. Unlike the process with an integrated protector, when SharePoint Foundation 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 SharePoint Foundation installation. However, you can register only one file type with a single protector.
Both types of protectors must implement the I_IrmProtector interface, described below.
The I_IrmProtector Interface
Each IRM protector must be a COM component that implements the I_IrmProtector Interface. Implementing this interface guarantees that the protector provides SharePoint Foundation 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.
Setting 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 SharePoint Foundation.
While both integrated and autonomous protectors must implement the I_IrmProtector interface, each type of protector implements the interface differently, because SharePoint Foundation calls the two types by using different methods of the interface. SharePoint Foundation invokes integrated protectors by using the I_IrmProtector.HrProtectRMS Method method and the I_IrmProtector.HrUnprotectRMS Method method. SharePoint Foundationinvokes autonomous protectors by using the I_IrmProtector.HrProtect Method method and the I_IrmProtector.HrUnprotect Method method. This enables SharePoint Foundation 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 to rights-manage the files.
After you have compiled your custom IRM protector, you must register that protector with SharePoint Foundation so that it can be made available for document libraries.
For information about registering IRM protectors, see How to: Register an IRM Protector.
See Also
Tasks
How to: Register an IRM Protector
Reference
Concepts
Information Rights Management in SharePoint Foundation