IRM File Processing
Applies to: SharePoint Foundation 2010
You can understand how the components of the Information Rights Management (IRM) system in Microsoft SharePoint Foundation work together to enable rights-managed content in document libraries by examining the two basic processes for rights-managed content:
Downloading a protected document
Uploading that document back to the document library
The following scenarios are designed to give you a general understanding of how SharePoint Foundation processes rights-managed documents. They do not provide end-to-end procedures, and the actual process may vary for you, depending on the IRM settings that you specify for the document library.
Downloading IRM-Protected Documents from SharePoint Foundation
When a user requests a file from a document library that has IRM enabled, SharePoint Foundation first performs its standard processing, such as synching document metadata. If the document is rights-managed, SharePoint Foundation determines whether an IRM protector associated with the document's file type is registered. If not, SharePoint Foundation downloads the document to the user without rights management protection.
If an appropriate IRM protector is registered, and that protector is an integrated protector, SharePoint Foundation generates an issuance license (IL) for the document. The IL includes:
A document key that is specific to the document. This private key is used to encrypt data in the rights-managed document.
A list of users who can access the document, and their corresponding permissions. SharePoint Foundation adds itself and the user who downloaded the document to this list.
The GUID of the document library from which this document is being downloaded.
SharePoint Foundation then calls the IRM protector to determine whether the document is already rights-managed. For example, the document might have had rights management applied to it in a client application before it was uploaded to the document library. If the file is already rights-managed, SharePoint Foundation downloads the document to the user without additional rights management protection.
If you set your document library to accept only documents that SharePoint Foundation can rights-manage, the user cannot upload documents that have had rights-management protection applied by an application other than SharePoint Foundation.
If the document requires protection, SharePoint Foundation calls the IRM protector to create a file stream that represents an IRM-protected version of the document:
If the protector is an integrated protector, SharePoint Foundation provides the IRM protector with access to the RMS encryption process. SharePoint Foundation also provides the IRM protector access to the IL of the document and the server end-user license (EUL). The IRM protector includes both in the protected file.
If the protector is an autonomous protector, SharePoint Foundation provides the IRM protector rights data and other metadata about the document. The autonomous protector must then configure and execute its own rights-management process to produce a rights-managed version of the requested file. The autonomous protector may use RMS directly, or it may use some other rights-management process to create the protected document.
In either case, if the IRM protector succeeds, SharePoint Foundation downloads the protected document to the user. If the protector cannot rights-manage the document, SharePoint Foundation downloads the document to the user without rights-management protection. If the IRM protector encounters a major error, SharePoint Foundation cancels the download of the document.
Specifically, SharePoint Foundation downloads the document to the user without rights-management protection if the IRM protector returns one of the following error codes:
MSOIPI_STATUS_ALREADY_PROTECTED The file is already IRM protected.
MSOIPI_STATUS_CANT_PROTECT A general failure of the protector.
MSOIPI_STATUS_NOT_MY_FILE The specified file is not of a file type associated with this IRM protector.
Errors of these types should be rare; for example, SharePoint Foundation selects the appropriate protector based on file type, and calls the protector to determine whether the file is already rights-managed, before processing reaches the points where SharePoint Foundation would call the protector to encrypt the file.
It is the responsibility of the developer who creates the custom protector to determine when to return the above error codes, or whether the protector should ever return those codes. If you never want to provide an unencrypted file, then do not program your protector to return these codes to SharePoint Foundation.
After the requested file is downloaded to the user's computer, the client application decrypts the file by directly contacting the rights-management service used by the protector, whether it is an RMS server or other rights-management server. In the case of RMS, the client application requests a EUL for the document. In the case of other rights-management services, the client application requests analogous permissions to the file.
Figure 1 shows the general process flow that occurs when a user requests a rights-managed document from a document library.
Figure 1. Process flow when a user requests a rights-managed document
Uploading IRM-Protected Documents to SharePoint Foundation
When a user checks a protected file into a document library, SharePoint Foundation again determines whether there is a registered IRM protector that handles the document's file type. If there is not, SharePoint Foundation uploads the document without performing any further decryption or processing. However, if the document library is configured to reject items that cannot be rights-managed, SharePoint Foundation cancels the file upload instead.
If SharePoint Foundation finds an appropriate IRM protector, SharePoint Foundation calls it to generate a file stream that represents an unprotected version of the document:
The IRM protector returns the IL to SharePoint Foundation. SharePoint Foundation compares the document library GUID stored in the document IL with that of the library to which the document is being uploaded.
If the protector is an integrated protector, the IRM protector may request that SharePoint Foundation provide it with access to the RMS decryption process.
If the protector is an autonomous protector, the IRM protector configures and executes the decryption process. It returns the document library GUID for the document directly to SharePoint Foundation. SharePoint Foundation then compares the document library GUID returned by the autonomous protector with that of the library to which the document is being uploaded.
In each case, SharePoint Foundation does the following:
If the document library GUIDs match, the IRM protector successfully generates the file stream, and SharePoint Foundation consumes the file stream to generate an unprotected version of the document.
SharePoint Foundation then performs its standard processing, such as synching document metadata, and stores the document.
If the document library GUIDs do not match, SharePoint Foundation cancels the document upload.
Figure 2 shows the general process flow that occurs when a user checks in a rights-managed document.
Figure 2. Process flow when a user checks in a rights-managed document