Microsoft 信息保护 SDK - 保护处理程序概念

  • 项目

在 MIP 保护 SDK 中，mip::ProtectionHandler 公开的函数用于加密和解密受保护的流和缓冲区、执行访问检查、获取发布许可证以及从受保护信息中获取属性。

要求

要创建要用于特定文件的 ProtectionHandler，需要满足以下条件：

  • 执行 mip::MipContext 操作
  • 执行 mip::ProtectionProfile 操作
  • 添加到 ProtectionProfile 的 mip::ProtectionEngine
  • 继承 mip::ProtectionHandler::Observer 的类。
  • mip::ProtectionDescriptor 或发布许可证

创建保护处理程序

mip::ProtectionHandler 对象是为“保护”或“消耗”操作构造的。 处理程序是使用以下四个函数中的一个创建的，具体取决于相应的场景。

  • mip::ProtectionEngine->CreateProtectionHandlerForConsumptionAsync()
  • mip::ProtectionEngine->CreateProtectionHandlerForConsumption()
  • mip::ProtectionEngine->CreateProtectionHandlerForPublishingAsync()
  • mip::ProtectionEngine->CreateProtectionHandlerForPublishing()

这些函数接受 mip::ProtectionHandler::PublishingSettings 或 mip::ProtectionHandler::ConsumptionSettings 对象。

创建发布处理程序

创建发布处理程序需要三个步骤：

  1. 创建 mip::ProtectionDescriptor 对象。
  2. 使用 mip::ProtectionDescriptor 将 mip::ProtectionHandler::PublishingSettings 实例化。
  3. 调用 mip::ProtectionEngine::CreateProtectionHandlerForPublishingAsync() 以传入 PublishingSettings 对象、观察者和承诺。

利用描述符创建

如果保护尚未保护的内容，或者对内容应用新的保护（这意味着已解密），必须构造一个 mip::ProtectionDescriptor。 完成构造后，它将用于实例化 mip::ProtectionHandler::PublishingSettings() 对象。 结果将通过 mip::ProtectionHandler::Observer 返回。

// Create the protection descriptor, passing in a templateId. 
auto descriptorBuilder = mip::ProtectionDescriptorBuilder::CreateFromTemplate(protectionOptions.templateId);
std::shared_ptr<mip::ProtectionDescriptor> descriptor = descriptorBuilder->Build();

// Define the handler promise, future, and observer.
auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<ProtectionHandler>>>();
auto handlerFuture = handlerPromise->get_future();
auto handlerObserver = std::make_shared<ProtectionHandlerObserverImpl>();

// Create the PublishingSettings object using the previously-created descriptor as input.
mip::ProtectionHandler::PublishingSettings publishingSettings = mip::ProtectionHandler::PublishingSettings(descriptor);

// Create/get the publishing handler from the publishing settings, observer, and promise.
mEngine->CreateProtectionHandlerForPublishingAsync(publishingSettings, handlerObserver, handlerPromise);
auto handler = handlerFuture.get();
return handler;

成功创建 ProtectionHandler 对象后，可以执行保护操作（加密/解密）。 “发布许可证”必须从处理程序提取，并使用加密内容进行存储。 发布许可证可以通过调用以下命令提取：handler->GetSerializedPublishingLicense();

没有相应发布许可证的受保护内容无法解密。

创建消耗处理程序

创建发布处理程序需要三个步骤：

  1. 从受保护内容中提取序列化的发布许可证 std::vector<uint8_t>。
  2. 使用序列化的发布许可证实例化 mip::ProtectionHandler::ConsumptionSettings。
  3. 调用 mip::ProtectionEngine::CreateProtectionHandlerForConsumptionAsync() 以传入 ConsumptionSettings 对象、观察者和承诺。

此示例假定已从某个源读取发布许可证并存储在 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);

// Define the handler promise, future, and observer.
auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<ProtectionHandler>>>();
auto handlerFuture = handlerPromise->get_future();
shared_ptr<ProtectionHandlerObserverImpl> handlerObserver = std::make_shared<ProtectionHandlerObserverImpl>();

// Create the consumption settings object from the publishing license.
mip::ProtectionHandler::ConsumptionSettings consumptionSettings = mip::ProtectionHandler::ConsumptionSettings(serializedPublishingLicense);

// Create/get the publishing handler from the publishing settings, observer, and promise.
mEngine->CreateProtectionHandlerForConsumptionAsync(consumptionSettings, handlerObserver, handlerPromise);
auto handler = handlerFuture.get();