Share via

Building a Protected Document Library

  • Article

You can use the AD RMS SDK to build a shared document library that can protect and deliver AD RMS-protected documents on demand. The following scenario presents a hypothetical interaction between an end user and a document library.

To publish a file to the document library

  1. A user saves a file locally as an MHT file.

  2. The user navigates to the library Web page and specifies the location of the saved MHT file to submit to the library.

  3. The Web application uploads the file and encrypts it. For more information, see Encrypting Content by Using AD RMS Functions and Encrypting Content by Using CryptoAPI Functions.

  4. The Web application creates a signed issuance license for the file. This license specifies who has view, print, or other rights to the file. The Web application does this by reading the access control lists (ACLs) that are assigned to users or groups in the document library and by translating ACLs to rights that the Active Directory Rights Management Add-on for Internet Explorer supports, as follows.

    ACL Right
    read VIEW
    write EDIT

    Users and groups are designated by security identifiers (SIDs), or Windows IDs, in the license, but a Passport ID (PUID) or just an e-mail address is also acceptable. Simple e-mail validation is less secure, though; for more information, see Creating an Issuance License and Getting the Issuance License Signed. Note, however, that to also acquire a use license on behalf of the user, the only valid form of identification is a Windows e-mail address.

  5. The Web application puts both the encrypted .mht file and the signed issuance license into a file called a compound file. This file, which has an .rmh extension, is used by the Active Directory Rights Management Add-on for Internet Explorer to permit viewing of AD RMS-protected content in Internet Explorer. For more information, see Compound Files. You can use your own format if you are not using the add-on; for more information, see Creating a Compound File and Adding Content, and Adding the Issuance License to the Compound File.

  6. The Web application stores the compound file, and adds it to the list of available documents.

To obtain and use a protected document from the library

  1. A prospective user navigates to the document library by using a Web browser, selects a document, and enters their e-mail address.
  2. The Web application retrieves the compound file from storage.
  3. The Web application extracts the existing issuance license from the compound file and creates a new issuance license for the content. This allows the most recent ACLs to be used for the license. For more information, see Updating the Issuance License.
  4. The Web application republishes the issuance license by using the EditIssuanceLicense method on the service. This method takes the content key from the old issuance license, and puts it into the new issuance license, using all new issuance license data. The application replaces the original signed issuance license in the compound file with the new one. For more information, see Updating the Issuance License.
  5. The Web application acquires a use license for the user by calling the AcquirePreLicense Web method, passing in the user's identity and the new issuance license. This is an optional step. Acquiring a use license on behalf of a user allows the user to view the document immediately, without having to visit a licensing service (if they are granted rights). For more information, see Acquiring the Use License.
  6. The use license is added to the compound file. For more information, see Adding the Use License to the Compound File.
  7. The Web application sends the compound file down to the user.
  8. The user's browser detects an AD RMS-protected container file based on the .rmh extension of the compound file and loads the Active Directory Rights Management Add-on for Internet Explorer, which reads the container file, binds to the use license, and performs all the actions granted to that user (such as displaying the document, allowing the user to extract it, and so on).

See Also

Building a Publishing Application Without Using a Lockbox

Send comments about this topic to Microsoft

Build date: 3/13/2008