Microsoft Information Protection SDK - Protection handler concepts
In the MIP Protection SDK, the 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.
Requirements
Creating a ProtectionHandler to work with a specific file requires:
- A
mip::MipContext - A
mip::ProtectionProfile - A
mip::ProtectionEngineadded to theProtectionProfile - A class that inherits
mip::ProtectionHandler::Observer. - A
mip::ProtectionDescriptoror publishing license
Create a protection handler
mip::ProtectionHandler objects are constructed by providing either a ProtectionDescriptor or a serialized publishing license to one of two ProtectionEngine functions. The protection descriptor must be generated for protecting plaintext information that doesn't already have a publishing license. The publishing license will be used when decrypting already-protected content or when protecting content where the license has already been constructed. Protected content cannot be decrypted without the associated publishing license.
mip::ProtectionEngine exposes two functions for creating a ProtectionHandler. The parameters are the same, with the exception of the handler or the publishing license as the first parameter.
mip::ProtectionEngine::CreateProtectionHandlerFromDescriptorAsync- Requires a
ProtectionDescriptoras the first parameter.
- Requires a
mip::ProtectionEngine::CreateProtectionHandlerFromPublishingLicenseAsync- Requires a serialized publishing license, stored in
std::vector<unint8_t>as the first parameter.
- Requires a serialized publishing license, stored in
Create from descriptor
If protecting content that hasn't yet been protected, or when applying new protection to content, which implies that it's been decrypted, a mip::ProtectionDescriptor must be constructed. Once constructed, is passed in to mip::ProtectionEngine::CreateProtectionHandlerFromDescriptorAsync() and the result is returned via the mip::ProtectionHandler::Observer.
auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<ProtectionHandler>>>();
auto handlerFuture = handlerPromise->get_future();
auto observer = std::make_shared<ProtectionHandlerObserverImpl>();
//Refer to ProtectionDescriptor docs for details on creating the descriptor
auto descriptor = CreateProtectionDescriptor(); //Stub function
mEngine->CreateProtectionHandlerFromDescriptorAsync(
descriptor,
mip::ProtectionHandlerCreationOptions::None,
observer,
handlerPromise);
auto handler = handlerFuture.get();
After successfully creating the ProtectionHandler object, file operations (get/set/delete/commit) can be performed.
Create from publishing license
This example assumes that the publishing license has already been read from some source and stored in std::vector<uint8_t> serializedPublishingLicense.
//TODO: Implement GetPublishingLicense()
//Snip implies that function reads PL from source file, database, stream, etc.
std::vector<uint8_t> serializedPublishingLicense = GetPublishingLicense(filePath);
auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<ProtectionHandler>>>();
auto handlerFuture = handlerPromise->get_future();
shared_ptr<ProtectionHandlerObserverImpl> handleObserver =
std::make_shared<ProtectionHandlerObserverImpl>();
mEngine->CreateProtectionHandlerFromPublishingLicenseAsync(
serializedPublishingLicense,
mip::ProtectionHandlerCreationOptions::None,
handleObserver,
handlerPromise);
auto handler = handlerFuture.get();