Inside SharePointIntegrate Information Rights Management into SharePoint

Pav Cherny

Code download available at: ChernySharePoint2009_05.exe(871 KB)

Contents

AD RMS Production and Preproduction Hierarchies
AD RMS Preproduction Topology
Preproduction Server Configuration
SharePoint IRM Configuration Issues
Preproduction-Specific Issues
Compilation and Registration
IRM Protector Testing
Deploying Custom IRM Document Protectors
Conclusion

Microsoft Office SharePoint Server (MOSS) 2007 ships with protectors based on the Information Rights Management (IRM) framework. These provide Microsoft Office users with the benefit of SharePoint integration with Active Directory Rights Management Services (AD RMS). Unfortunately, Windows SharePoint Services ( WSS ) 3.0 does not include IRM protectors out of the box. However, there is a solution. If you browse the sample applications and code snippets on the MSDN Code Gallery, among the gems you'll find is the Microsoft Office File Format Protectors source code, which Microsoft published in August 2008. The source code comes with a non-exclusive, worldwide, royalty-free "as-is" Microsoft Public License (Ms-PL). This is a great find because it means you can compile the source code and add these components to WSS 3.0 as well. In this way, you can benefit from AD RMS-based security and compliance features in any SharePoint environment.

In this column, I continue last month's discussion about SharePoint integration with AD RMS by showing you how to establish an AD RMS preproduction development environment, compile the IRM protectors, and integrate the compiled components into WSS 3.0. You don't actually need a preproduction environment to compile the IRM protectors, but it's an interesting exercise because it highlights some typical AD RMS configuration issues that you might encounter in a production environment. You don't need to be a C/C++ developer to understand the concepts around AD RMS production and preproduction hierarchies and how they affect the deployment of AD RMS, Microsoft Office, and WSS 3.0. And you don't need C/C++ development skills to compile and test IRM protectors. Developer topics, such as extending the source code or converting integrated protectors into autonomous protectors, are beyond the scope of this article. The only developer task you will encounter concerns the creation of a setup project with a few mouse clicks to simplify the deployment of the compiled protector components on your WSS 3.0 production servers. The May companion material (available on the code download page of TechNet Magazine) includes worksheets and tools that guide you through the deployment, compilation, and test procedures on computers running the x64 version of Windows Server 2008.

AD RMS Production and Preproduction Hierarchies

SharePoint, like any other application that wants to use AD RMS to encrypt or decrypt content, must have a digitally signed manifest that signs the application into the AD RMS hierarchy. This manifest defines those modules that can and cannot be loaded into the address space of the application in order to create a secure environment and protect the unencrypted content in memory. For a manifest to be valid, it must be digitally signed by a certificate authority (CA) that belongs to an AD RMS certificate hierarchy. This can be the production hierarchy with an application-signing CA controlled exclusively by Microsoft, or it can be the preproduction hierarchy that enables developers to self-sign application manifests. Note that a manifest can belong to either hierarchy, but not both. A manifest signed by a production CA is invalid in the preproduction hierarchy and vice versa because the hierarchies have different root authorities. Application manifests are covered in detail in the AD RMS SDK.

When you install the first AD RMS server in an Active Directory forest, you implicitly establish the AD RMS hierarchy. By default, the AD RMS installation routine uses a Microsoft DRM Server Self Enrollment Service CA to issue the Server Licensor Certificate (SLC), which is part of the hierarchy that leads back to the Microsoft DRM Production Root at the root of trust. Figure 1 shows this certification chain, derived from the SLC of a production AD RMS server. If you want to examine the AD RMS hierarchy in your own environment, check out the companion material, which includes the AD RMS Certificate Chain tool (CertificateChain.exe).

Figure 1 The AD RMS Application Signing Certifi cate belongs to the AD RMS preproduction hierarchy.

The Microsoft DRM Production Root establishes the production hierarchy, and Microsoft requires all software vendors to sign a Production License Agreement as a prerequisite to obtaining a production certificate and signing applications into the production hierarchy. The purpose of the production certificate is to create and sign manifests for released applications. For development purposes, you should use a preproduction certificate instead. Originally, Microsoft also required software vendors to sign a Development License Agreement to obtain a preproduction certificate, but a public key (ISVTier5AppSIgningPubKey.dat), private key (ISVTier5AppSigningPrivKey.dat), and the corresponding preproduction certificate (ISVTier5AppSignSDK_Client.xml) are now included in the AD RMS SDK so that you can sign manifests during development without having to contact Microsoft. As a side note, the keys and preproduction certificate are also included in the Microsoft Office File Format Protectors source code package.

Signing an application manifest using the preproduction certificate implies that you can't use the application in conjunction with a production AD RMS server. As Figure 1 reveals, the root issuer in the certificate chain of isvtier5appsignsdk_client.xml is Microsoft DRM ISV Root, which is clearly not the root of a production server. You can examine isvtier5appsignsdk_client.xml using my AD RMS Certificate Chain tool. It follows that you need an AD RMS server with a different SLC that has the Microsoft DRM ISV Root at the root of trust (see Figure 1). To deploy such an AD RMS server, you must establish a separate Active Directory forest for your development environment.

AD RMS Preproduction Topology

With a separate Active Directory forest, it is a good idea to give some thought to the AD RMS preproduction topology. Specifically, you must decide whether you want to install AD RMS on a standalone server or directly on the domain controller. In most cases, a domain controller deployment is sufficient for development purposes. Note that this is not a recommendation for production environments. In a production environment, you must not deploy AD RMS on a domain controller because the domain user account that you specify as the AD RMS network identity would then require domain administrator permissions to log on locally. Logging on locally is an administrator privilege on domain controllers. On a member server, the domain user account doesn't need elevated permissions at all. If you are unsure about the domain controller question in production environments, read Jason Tyler's blog article "The DOs and DON'Ts of RMS." Regarding the idea of putting RMS on a domain controller, Jason says, "This is such a bad idea, that every time I see it, I want to go tell the person to go pick a switch and meet me behind the toolshed."

The next question is whether to install WSS 3.0, Office 2007, and Microsoft Visual Studio 2008 on the domain controller. Here you should definitely use a separate server, even in a development environment. As with the AD RMS issue, the security configuration of WSS 3.0 differs on domain controllers in comparison with member servers. By using a member server, you retain a configuration comparable to a WSS 3.0 production environment, which delivers more reliable results when testing compiled components. Of course, you can keep the domain controller and the member server on a single physical computer if you use Microsoft Hyper-V Server 2008, as illustrated in Figure 2. Hyper-V is 64-bit virtualization technology, so you can use the x64 edition of Windows Server 2008 on both virtual machines. Note that Hyper-V Server 2008 doesn't include graphical management tools, but you can install Hyper-V Server Remote Management Tools on a separate Windows Vista workstation, as outlined in the companion worksheet "Installing Hyper-V Server Remote Management on a Windows Vista Workstation."

Figure 2 A small-scale AD RMS development environment on a Hyper-V host.

Preproduction Server Configuration

Before installing the Active Directory Rights Management Services role, you must configure certain registry settings on the server so that the AD RMS installation enrolls the server in the preproduction hierarchy. If you skip this configuration step, you'll end up with the wrong hierarchy. Keep in mind that you cannot move an AD RMS server between hierarchies. If your server is enrolled in the production hierarchy, you must uninstall AD RMS, delete the AD RMS service connection point (SCP) in Active Directory, configure the registry, and then install the Active Directory Rights Management Services role again.

Figure 3 lists the registry setting that determines the AD RMS hierarchy on a computer running Windows Server 2008. Setting the Hierarchy parameter to 1 enables the preproduction hierarchy. A value of 0 or the absence of this parameter indicates that AD RMS should deploy in the production hierarchy. Additional registry settings exist for backward compatibility, but this is not a requirement in our development environment. For details, see the topic "Configure the Registry" in the AD RMS SDK. The following code can be saved as a registry (.reg) file to enable the preproduction hierarchy on an AD RMS server.

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DRMS\2.0]
"Hierarchy"=dword:00000001

Figure 3 The AD RMS client can’t access the AD RMS server.

SharePoint IRM Configuration Issues

The AD RMS server deployment and configuration is relatively uncomplicated. Trickier is the configuration of the member server running WSS 3.0 to sign SharePoint into the preproduction hierarchy. You can't just start SharePoint 3.0 Central Administration, switch to the Operations tab, click on Information Rights Management, and then select the option Use the default RMS server specified in Active Directory. Clicking OK would result only in the error message displayed in Figure 3. As the message reveals, the AD RMS client (msdrm.dll) is present; it is installed with Windows Server 2008 by default, but the AD RMS server is inaccessible.

Unfortunately, neither error message, nor trace log, nor application event log reveal the true nature of the issue. One option to get more detailed information is to access the URL specified in the Trace log directly in Internet Explorer, for example, https://adrms.litware.com:443/\_wmcs/certification. Most likely, Internet Explorer reports a "problem with this website's security certificate" if the preproduction AD RMS server uses a self-signed secure sockets layer (SSL) certificate that the client doesn't trust. To trust the server's SSL certificate, you must install the SSL certificate in the Trusted Root Certification Authorities store on the local computer. Make sure you place the certificate in the physical store of the local computer because you must make the certificate available to all SharePoint security accounts, not just your own user account. The companion worksheet "Deploying WSS01 in the AD RMS Preproduction Environment" describes the steps.

Sometimes, it can be difficult to deal with self-signed SSL certificates. SharePoint determines the URL of the AD RMS Certification Web Service by means of the AD RMS SCP in Active Directory. If that SCP specifies a URL with a host name that differs from the host name in the Web server's SSL certificate, the Web server remains not trusted even after you install the SSL certificate in the Trusted Root Certification Authorities store. Figure 4 shows a common configuration scenario that leads to this issue. The configuration uses an alias in the AD RMS URL that differs from the actual host name. This facilitates server maintenance and disaster recovery because you can't change the AD RMS URL after the deployment of an AD RMS server, yet the CNAME record enables you to point the URL at a different server if necessary. As the four steps in Figure 4 indicate, first, the SharePoint server looks up the serviceBindingInformation attribute of the AD RMS SCP to determine the AD RMS URL. Next, it resolves the host name adrms.litware.com to dc01.litware.com based on the CNAME record. SharePoint then connects to dc01.litware.com, which returns the SSL certificate for dc01.litware.com, and this causes the mismatched address conflict.

Figure 4 The SSL certificate is not trusted due to a name mismatch.

To solve this conflict, issue an SSL certificate for adrms.litware.com on the AD RMS server by using the SelfSSL tool available in the Internet Information Services (IIS) 6.0 Resource Kit. The companion worksheet "Deploying DC01 in the AD RMS Preproduction Environment" includes download information and step-by-step instructions.

Fixing SSL certificate issues is the first step toward a functioning configuration, but a trusted SSL certificate isn't the only requirement. If you attempt to configure IRM without first granting the security account of the Central Administration application pool read and execute access, you receive the error message IRM will not work until the server grants permission. Domain account name used: WSS01$@litware.com. You get this error because the client must call the Certify method of the AD RMS Certification Web Service to obtain a Rights Account Certificate (RAC), which fails due to missing access permissions to the ServerCertification.asmx file. By default, only the AD RMS server's SYSTEM account has access. The recommended solution is to inherit permissions from the certification folder on ServerCertification.asmx and then add the computer accounts of your WSS 3.0 server(s) with read and execute permissions as well. This ensures that all potential application pool accounts have the required permissions. See the companion worksheet "Deploying DC01 in the AD RMS Preproduction Environment" for details.

Preproduction-Specific Issues

At this point, the IRM framework should be functional, except when you are in a preproduction environment. Remember that AD RMS client and applications must use a different certificate chain here. If you attempt to configure the IRM framework in the original configuration, you receive the error "The required Windows Rights Management client is present but could not be configured properly," and the trace log includes another useful hint, "The machine was not activated." This is an indicator that the AD RMS client is still in the production hierarchy. You can verify this in Registry Editor. Check the registry keys HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\uDRM\Hierarchy and HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\uDRM\Hierarchy. A value of 0 designates the production hierarchy. Changing these values to 1 activates the preproduction hierarchy. The following code lists a .reg file to apply the configuration changes conveniently.

Windows Registry Editor Version 5.00

 [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\uDRM]
"Hierarchy"=dword:00000001

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\uDRM]
"Hierarchy"=dword:00000001

However, don't be surprised that the registry changes aren't effective immediately. The error remains because the AD RMS client has already generated an incorrect machine certificate during the first unsuccessful attempt and continues to use this certificate. On your WSS server, open the C:\ProgramData\Microsoft\DRM\Server folder and delete all subfolders and files. You might also want to check the %LOCALAPPDATA%\Microsoft folder. If it includes a \DRM subfolder, delete the subfolder because it stores client licenses that aren't usable anymore in the preproduction hierarchy. The AD RMS client recreates these subfolders and certificate files within them as necessary.

Switching back to SharePoint 3.0 Central Administration, try again to configure IRM and don't let the next error message fool you: It's the same error message as before but the error reason is actually different. Check the trace log and you'll find that "There was a problem while creating and initializing a secure environment…" Now this is a manifest issue! SharePoint still uses the production manifest as the AD RMS Certificate Chain tool reveals if you open the Stsprtid.xml file located in the %PROGRAMFILES%\Common Files\Microsoft Shared\Web Server Extensions\12\Bin folder (see Figure 5).

Figure 5 The production manifest doesn’t work in the preproduction hierarchy.

You must delete (or rename) the production Stsprtid.xml file, generate a new manifest by using the Genmanifest.exe tool included in the AD RMS SDK as well as in the Microsoft Office File Format Protectors download package, and then restart IIS. The download package even comes with a SharePoint configuration file (sharepoint.mcf) and batch files (genmft.bat and genmft.64.bat) to simplify this task. Still, the batch file for 64-bit environments only signs Microsoft Office applications into the preproduction hierarchy and skips SharePoint. To sign in SharePoint on a 64-bit server, use the Sharepoint.bat file included in the companion material or use the Genmanifest.exe tool directly. The command syntax is

Genmanifest.exe -chain isvtier5appsignsdk_client.xml sharepoint.mcf
 Stsprtid.xml

See also the Genmanifest.exe page at msdn.microsoft.com/en-us/library/aa362621(VS.85).aspx.

Compilation and Registration

Having replaced the SharePoint manifest file, you can successfully complete the IRM configuration. We have finished the hard part. Now it's time to reap the rewards by compiling and testing the protector components. This is a straightforward undertaking. The source code comes with Visual Studio 2005 projects that you can upgrade to Visual Studio 2008 without problems. However, keep in mind that you are working on a 64-bit server. The Visual Studio projects are configured for a 32-bit environment. You must change this configuration to compile the components for the x64 platform, as illustrated in Figure 6. See also the companion worksheet "Compiling, Testing, and Deploying Microsoft Office File Format Protectors."

Figure 6 To use IRM protectors on a 64-bit WSS server, compile the source code for the x64 platform.

Visual Studio takes care of the COM component registration at build time, but you still must register the IRM protectors in WSS 3.0. Register the components with their class identifiers (CLSID) under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Shared Tools\Web Server Extensions\12.0\IrmProtectors. Here is a registry file that accomplishes this step:

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Shared Tools\Web Server
 Extensions\12.0\IrmProtectors]
"{2E4402B2-F2DA-4BC8-BB2C-41BECF0BDDDB}"="MsoIrmProtector"
"{81273702-956F-4CBD-9B16-43790558EE29}"="OpcIrmProtector"

You can also check the content of the IrmProtectors.reg file in the companion material. It contains additional keys for informational purposes. I included these keys because the IRM protectors of MOSS 2007 have similar entries. The only difference is that MOSS protectors actually use their settings while our IRM protectors use hard-coded values instead.

IRM Protector Testing

Now that WSS is aware of the IRM protectors, you can restart IIS, open your SharePoint site, configure an AD RMS policy for a document library, and then create, upload, and download documents to verify that the IRM protectors work. However, this can be time-consuming if you are struggling with basic COM registration issues. For example, if you forgot to activate the x64-bit platform in Visual Studio, the compilation process completes without errors, but the COM registration remains incomplete, WSS cannot load the protectors, and you will not be able to test AD RMS protection. You can save time by checking the COM registration first and performing tests in SharePoint only if the registration check shows complete success. Figure 7 shows a basic script to check the COM registration. It simply loads the COM components and displays a message box with the results.

On Error Resume Next
set MsoIrmProtector=NOTHING 
set OpcIrmProtector=NOTHING 

set MsoIrmProtector=CreateObject("MsoIrmProtector.MsoIrmProtector")
set OpcIrmProtector=CreateObject("OpcIrmProtector.OpcIrmProtector")

IF MsoIrmProtector IS NOTHING AND OpcIrmProtector IS NOTHING THEN
   Wscript.Echo "Unable to load MsoIrmProtector and OpcIrmProtector."
ELSEIF MsoIrmProtector IS NOTHING THEN
          Wscript.Echo "OpcIrmProtector loaded successfully, but
           unable to load MsoIrmProtector."
ELSEIF OpcIrmProtector IS NOTHING THEN
          Wscript.Echo "MsoIrmProtector loaded successfully, but
           unable to load OpcIrmProtector."
ELSE
Wscript.Echo "MsoIrmProtector and OpcIrmProtector loaded
           successfully."
END IF

Figure 7 Make sure IRM protectors are properly registered as COM components before testing the protectors in SharePoint.

On Error Resume Next
set MsoIrmProtector=NOTHING 
set OpcIrmProtector=NOTHING 

set MsoIrmProtector=CreateObject("MsoIrmProtector.MsoIrmProtector")
set OpcIrmProtector=CreateObject("OpcIrmProtector.OpcIrmProtector")

IF MsoIrmProtector IS NOTHING AND OpcIrmProtector IS NOTHING THEN
   Wscript.Echo "Unable to load MsoIrmProtector and OpcIrmProtector."
ELSEIF MsoIrmProtector IS NOTHING THEN
          Wscript.Echo "OpcIrmProtector loaded successfully, but
           unable to load MsoIrmProtector."
ELSEIF OpcIrmProtector IS NOTHING THEN
          Wscript.Echo "MsoIrmProtector loaded successfully, but
           unable to load OpcIrmProtector."
ELSE
Wscript.Echo "MsoIrmProtector and OpcIrmProtector loaded
           successfully."
END IF

With proper registration settings, the OpcIrmProtector component for Office 2007 document formats is immediately functional. However, the MsoIrmProtector component for legacy Office formats has an additional requirement. The folder that contains the MsoIrmProtector.dll must also contain a \1033 subfolder with template files. The template files come with the source code and are located in the \MsoIrmProtector\Templates folder. You must copy these files into the \1033 subfolder so that the MsoIrmProtector component can include them into AD RMS–protected documents for backward compatibility with Office applications that do not support AD RMS, such as Office 2000 and Office XP. Otherwise, you will not be able to open legacy Office documents. For example, you'll receive the error displayed in Figure 8 when you attempt to create a new Word document in a document library.

Figure 8 Word can’t read this document because the MsoIrmProtector is unable to create the document in proper format without the template files.

Deploying Custom IRM Document Protectors

Congratulations! You have successfully built, registered, and tested custom IRM protectors for WSS 3.0. Now, how do you get these components onto your WSS 3.0 production servers? After all, you must install the IRM protectors on all your servers if you want to use these components in your production environment. Performing the deployment manually would be tedious and error-prone. It's better to build a Setup project, include the DLLs and template documents within the required file structure, import the necessary registry settings to integrate the components into WSS 3.0, and then use the resulting Microsoft Windows Installer (.msi) file for deployment.

It is also a good idea to test the deployment on a reference system. Among other things, such testing reveals important prerequisites you must meet before deploying the components. Specifically, Visual Studio 2008 adds Microsoft .NET Framework 3.5 SP1 dependencies to Setup.exe and the protector components require a Microsoft Visual C++ redistributable package. This is a standard requirement for executables and DLLs compiled with Visual C++. Make sure the redistributable package matches the version you use in your development environment. For example, if you use Microsoft Visual Studio 2008 SP1, then deploy the Microsoft Visual C++ 2008 SP1 Redistributable Package (x64). The companion worksheet "Testing the Microsoft Office File Format Protectors Deployment" demonstrates how to test the IRM protector deployment on a single server.

Conclusion

IRM-based protection of Microsoft Office documents used to require MOSS 2007, but by compiling the Microsoft Office File Format Protectors source code available on the MSDN Code Gallery you can integrate appropriate IRM protector components into WSS 3.0 as well. You can also modify the source code to implement custom features if you have C/C++ skills and have deployed SharePoint in an AD RMS preproduction environment. Keep in mind that your modifications affect all AD RMS–enabled document libraries. I recommend leaving the source code unaltered and checking the MSDN Code Gallery on a regular basis for updates and perhaps new versions with additional features, unless you are a developer looking for a great sample to integrate your own applications with the IRM framework. In this case, the source code is an excellent starting point.

Remember that Microsoft did not design the IRM framework to protect content items in SharePoint databases. You should not change the decryption routines, for example, or your SharePoint users might not be able to open the documents because the IRM framework grants only the application pool account and the current user AD RMS access permissions when protecting the content. Also keep in mind that certain protectors require other protectors to create a fully functional system. For example, the MsoIrmProtector protector for legacy Office document formats and the OpcIrmProtector protector for Office 2007 formats belong together. If you deployed the MsoIrmProtector protector without the OpcIrmProtector, a Word 2007 user might create a new document by using the template.doc content template in SharePoint, while saving the file as Doc1.docx. The MsoIrmProtector protector applies AD RMS protection to template.doc, so Doc1.docx would end up in the document library in rights-protected form because there is no OpcIrmProtector protector to decrypt the content upon upload. The application pool account and the current user would remain the only entities that can open this document. There are other ways to protect documents in SharePoint content databases through AD RMS, such as by using the ISPExternalBinaryStorage COM interface.

Pav Cherny is an IT expert and author specializing in Microsoft technologies for collaboration and unified communication. His publications include white papers, product manuals, and books with a focus on IT operations and system administration. Pav is President of Biblioso Corporation, a company that specializes in managed documentation and localization services.