Republishing

This overview focuses on republishing in MIP SDK. Republishing supports scenarios where an application allows a user to edit a file and needs to maintain the original publishing license information about owner, rights, content key, and so on.

The pattern might look like:

  • A user opens a protected document for editing.
  • The application permits the user to edit the file only if they have the appropriate rights.
  • The user edits and then saves the document.

The MIP SDK pseudocode to accomplish this task might look like:

  • Create an mip::FileHandler that points to the target file.
  • Store the mip::ProtectionHandler exposed by the mip::FileHandler's GetProtection() method.
  • Check that the user has EDIT rights by calling AccessCheck() method.
  • Use mip::FileHandler's GetDecryptedTemporaryFileAsync() or GetDecryptedTemporaryStreamAsync() to get a temporary decrypted output.
  • Edit the temp file or stream contents and save.
  • Create a new mip::FileHandler instance pointing to the temp file and use the SetProtection() method, providing the stored mip::ProtectionHandler as the parameter.
  • Commit the change.

By using the mip::ProtectionHandler from the original file, the application maintains the owner, content ID, and content key on the edited document. This republishing scenario requires the application to maintain a reference to the original mip::ProtectionHandler.

Implementation

As discussed earlier, the mip::FileHandler class exposes methods for reading, writing, and removing both labels and protection information. For the full list of supported operations, see the reference for mip::FileHandler.

This scenario uses the following methods of mip::FileHandler:

  • GetProtection()
  • CommitAsync()
  • GetDecryptedTemporaryFileAsync()
  • SetProtection()

The scenario also uses mip::ProtectionHandler, which exposes the functions for encrypting and decrypting protected streams and buffers, performing access checks, obtaining the publishing license, and getting attributes from the protected information. Use the AccessCheck() method to validate that the user has rights to edit the file.

To successfully complete this reprotection scenario, review the quickstarts under Next steps and verify that the application builds and can successfully list labels.

Create a protection handler from the file and decrypt the file

mip::ProtectionHandler exposes the functions for encrypting and decrypting protected streams and buffers, performing access checks, obtaining the publishing license, and getting attributes from the protected information. mip::ProtectionHandler objects are constructed by providing either a ProtectionDescriptor or a serialized publishing license. For this use case, the publishing license is used when decrypting already-protected content or when protecting content where the license has already been constructed.

mip::FileHandler exposes a method named GetProtection() that retrieves mip::ProtectionHandler from the file associated with the mip::FileHandler. After you retrieve the mip::ProtectionHandler object, you can use it to validate the user's access levels for the file, decrypt the file, and later encrypt the file after the user edits it.

Use mip::ProtectionHandler's AccessCheck() to validate that the user has a specific right to the file and return a boolean response, depending on the result. For example, to verify that the user has rights to edit, call the method and pass in the value "EDIT". If the result is true, permit the user to edit the file. After you verify the EDIT right, use mip::FileHandler's GetDecryptedTemporaryFileAsync() to retrieve the temporary decrypted file.

For more information, see Restrict access to content by using sensitivity labels to apply encryption.

Important

The application developer is responsible for access checks and enforcement. A user with VIEW rights can decrypt the protected information. The application must validate the set of rights granted to the user and enforce those rights through information protection controls, such as preventing copy, editing, or taking screenshots. If you don't implement protection controls correctly, you might expose sensitive information.

Save and publish the edited file by applying protection

You can edit the file after decrypting it. After the edit operation is complete, you can commit the changes. Use the temporary file to create an IFileHandler object that handles the committed file. Use the IProtectionHandler object retrieved from the original file to protect the temporary file.

Offline republishing

Republishing can take place offline when the publishing license cache is available. If the application has previously cached the templates and publishing license data through offline publishing, the republishing workflow doesn't require an active connection to the Rights Management service.

Offline republishing is useful in scenarios where:

  • The application must function in intermittently-connected environments.
  • Large batch operations need to republish without per-document service calls.
  • The application needs better performance by avoiding service calls.

Enable offline publishing and cache templates before attempting offline republishing. See Offline publishing for setup details.

Next steps

  • Last updated on