Microsoft Secure Tech Accelerator
Apr 03 2024, 07:00 AM - 11:00 AM (PDT)
Microsoft Tech Community
Now Available: Microsoft Information Protection SDK Version 1.3
Published Aug 22 2019 07:00 AM 2,208 Views
Microsoft

Now Available: Microsoft Information Protection SDK 1.3!

We're pleased to announce that the Microsoft Information Protection SDK version 1.3 is now generally available via NuGet and Download Center. We've added several new features to this release as well as performance and API improvements.

 

Highlights

  • Decryption of protected MSG files is now supported.
  • Inspection of message.rpmsg files is supported via mip::FileInspector and mip::FileHandler::InspectAsync().
  • On-disk cache may now be optionally encrypted.
  • Protection API now supports China sovereign cloud.
  • Arm64 support on Android.
  • Arm64e support on iOS.
  • End user license (EUL) cache can now be disabled.
  • .pfile encryption may be disabled via mip::FileEngine::EnablePFile
  • Improved performance for protection operations by reducing number of HTTP calls

 

MipContext

New in version 1.3 is the MipContext class. MipContext is now the highest-level object in MIP SDK and spans all profiles for the life for the application. The MipContext object is created and passed in to the various profile types. Here's an example for FileProfile.

 

 

 

 

mMipContext = mip::MipContext::Create(
     mAppInfo, //mip::ApplicationInfo  
          "file_sample", // MIP state path 
     mip::LogLevel::Trace, 
          nullptr /*loggerDelegateOverride*/, 
          nullptr /*telemetryOverride*/); 

FileProfile::Settings profileSettings(
          mMipContext, 
          mip::CacheStorageType::OnDiskEncrypted, 
          mAuthDelegate, 
          std::make_shared(), 
          std::make_shared());

 

 

 

 

 

MipContext has information about the application, cache storage path, and, optionally, logger and telemetry overrides. The object is passed in to the FileProfile::Settings constructor and then the profile is loaded. For details, visit our updated samples on GitHub.

 

The existing APIs will remain in place but have been marked as deprecated. They will be removed in the next version of the SDK.

 

Cache Storage Encryption

Previous versions, when creating a profile, had a bool parameter to specific whether storage was in memory or not. False indicated that state would be stored on disk. New in 1.3, we've removed this parameter and replaced it with mip::CacheStorageType. The cache storage can be OnDisk, InMemory, or OnDiskEncrypted.

 

When the type is set to OnDiskEncrypted, all policy and license information in the state databases are encrypted via locally available crytographic APIs. This encryption makes database tampering and browsing more difficult.

 

For full details on cache storage, including this new encryption feature, check out the cache storage concepts page on Microsoft Docs.

 

Delegation

Across the SDK, we've decoupled on-behalf-of operations from the mip::Identity class.

In previous versions of the SDK, if your application needed to perform an operation on behalf of the user, that delegated identity was required to have been set as a property of the mip::Identity object. mip::Identity was provided to the Engine for each of the three APIs, and all operations that engine performed were performed on behalf of that delegated user. Based on feedback from customers around the performance of that pattern, we've removed the delegated identity details from mip::Identity and instead added DelegatedUserEmail to mip::FileEngine::Settings, mip::ProtectionSettings, mip::PolicyEngine::Settings, and mip::ProtectionHandler's PublishingSettings and ConsumptionSettings.

 

A File API example of this in C# looks like:

 

 

 

var profile = Task.Run(async () => await MIP.LoadFileProfileAsync(profileSettings)).Result; // Create engine settings object 
var engineSettings = new FileEngineSettings("", "", "en-US") 
{ 
          // Provide the identity for service discovery. 
     Identity = new Identity("serviceprincipal@Contoso.com")
 }; 

// Add engine 
var engine = Task.Run(async () => await profile.AddEngineAsync(engineSettings)).Result; 

// Create protection settings, providing delegated identity 
ProtectionSettings protectionSettings = new ProtectionSettings() 
{ 
     DelegatedUserEmail = "Alice@Contoso.com" 
}; 

// Label will be set on behalf of Alice@Contoso.com 
handler.SetLabel(engine.GetLabelById(options.LabelId), labelingOptions, protectionSettings); 
var result = Task.Run(async () => await handler.CommitAsync(options.OutputName)).Result;

 

 

 

 

This new model helps to reduce round-trip times to the service involved in setup of new engine objects.

Label ID is now mip::Label

Functions that previously accepted a label identifier as an input now require a mip::Label object instead. Making this change in your application, in most cases, should be trivial and can be accomplished via mip::FileEngine::GetLabelById() or mip::PolicyEngine::GetLabelById().

 

 

 

 

// Old method 
handler.SetLabel(options.LabelId, labelingOptions, protectionSettings); 

// New method 
handler.SetLabel(engine.GetLabelById(options.LabelId), labelingOptions, protectionSettings);

 

 

 

 

In addition to SetLabel(), the following APIs use mip::Label instead of label ID.

  • mip::ApplyLabelAction::GetLabel - Previously GetLabelId
  • mip::RecommendLabelAction::GetLabel - Previously GetLabelId.
  • mip::ExecutionState::GetNewLabel - Previously GetNewLabelId.

 

Other Changes

  • In previous versions, we required that you called mip::ReleaseAllResources. Version 1.3 replaces this with mip::MipContext::~MipContext or mip::MipContext::Shutdown.
  • Removed ActionSource from mip::LabelingOptions and mip::ExecutionState::GetNewLabelActionSource
  • Replaced mip::ProtectionEngine::CreateProtectionHandlerFromDescriptor with mip::ProtectionEngine::CreateProtectionHandlerForPublishing.
  • Replaced mip::ProtectionEngine::CreateProtectionHandlerFromPublishingLicense with mip::ProtectionEngine::CreateProtectionHandlerForConsumption.
  • Renamed mip::PublishingLicenseContext to mip::PublishingLicenseInfo and updated to contain rich fields instead of raw serialized bytes.
  • mip::PublishingLicenseInfo contains the data relevant to MIP after parsing a publishing license (PL).
  • mip::TemplateNotFoundError and mip::LabelNotFoundError thrown when application passes MIP a template ID or label ID that is not recognized.
  • Added support for label-based conditional access via the claims parameter of AcquireToken() and mip::AuthDelegate::OAuth2Challenge(). This functionality hasn't yet been exposed via the Security and Compliance Center portal, but we will share details as soon as the settings are available.

@Tom Moser and the MIP SDK team

Version history
Last update:
‎May 11 2021 02:04 PM
Updated by: