We’re please to announce general availability of the Microsoft Information Protection SDK version 1.2!
Downloads are available via NuGet or direct downloads for all platforms.
New Platforms
In addition to the list of currently supported platforms, we are happy to announce support for the Protection API on iOS.
Highlights
- Exception handling is now consistent across all three APIs. Specifically:
ProxyAuthError
is thrown across MIP SDK if a proxy is configured to require authentication.NoAuthTokenError
is thrown across MIP SDK if an empty auth token is returned frommip::AuthDelegate::AcquireOAuth2Token
.
- Renamed
mip::ContentState
tomip::DataState
. - mip_common.dll split in to two DLLs: mip_core.dll and mip_telemetry.dll
- Improved HTTP caching for Policy API, cutting number of HTTP calls in half.
- Applications can now control threading behavior of async tasks by overriding
TaskDispatcherDelegate
in the File, Protection, or Policy Profile. - Improved debug logging across the SDK to assist with debugging and failure identification.
mip::FileExecutionState::GetAuditMetadata
can be implemented by applications to specify detailed information to surface to a tenant admin’s audit dashboard.
Preview: Decryption of Protected MSG Files
Since releasing the MIP SDK 1.0 in September of 2018, a common request from our ISV partners and customers has been to add support for decryption of protected mail. In version 1.2 we’re providing a public preview of the MSG file parser. Common protection and permutations of MSG files are supported in this first release. Protected emails and attachments in those mails will be decrypted and the resulting output will be an MSG file, decrypted, that resembles the original encrypted message.
The scenarios we’ve heard of from customers where this functionality is of particular interest are generally related to:
eDiscovery
As part of discovery, mail must be searched, decrypted, and provided to attorneys, or other groups, for litigation and supporting activities. The SDK can now help to decrypt those MSG files.
Data Loss Prevention
DLP products have a need to decrypt outbound items to scan for violations of DLP policy. DLP vendors will be able to use the SDK to decrypt mail messages to scan. Once the scan is complete, the decrypted copy is discarded and the encrypted copy is sent or blocked, depending on the result of the scan.
Mail Journaling
Many organizations have requirements to send mail to 3rd party systems for journaling. Today, encrypted mail makes those systems unable to search or discover any of the mail information. Journaling connectors can be made to use the MIP SDK to decrypt the message prior to sending to the journaling service.
A few important notes:
- We are treating this functionality as preview for now. Over the next couple of months we’ll continue to release minor updates for the SDK to address any bugs or functionality gaps with MSG parsing and plan to call this functionality GA and fully supported before our 1.3 release.
- The process is “lossy.” While we strive to maintain formatting and metadata, the decryption and re-assembly of the protected message to a plaintext message is a destructive operation.
- message.rpmsg files are not supported in this release. Message.rpmsg itself isn’t a useful file format. It must exist as an attachment in an email to be usefully-decrypted in most scenarios.
- EML and PST files are not supported.
- You may find in testing that certain messages don’t decrypt as expected. While we’re working to cover the most common use cases, we’re sure you’re going to find that email from the terabytes of PSTs in your environment and try to decrypt it. We may need some pretty specific feedback that includes sending a copy of the message.
- To submit feedback on issues, head over to https://aka.ms/MIPSDK-MSG-Feedback for details on how to collect information and submit feedback.
Enabling the Preview
We’ve set the MSG parsing capabilities behind a feature flag for now. Enabling the feature requires setting CustomSettings
in FileEngineSettings
prior to adding the engine.
C#
List<KeyValuePair<string, string>> customSettings = new List<KeyValuePair<string, string>>();
customSettings.Add(new KeyValuePair<string, string>(“enable_msg_file_type”, “true”)); //Enable msg file type.
var engineSettings = new FileEngineSettings(“”, “”, “en-US”) {
Identity = identity,
CustomSettings = customSettings // Add custom settings to engine.
};
C++
FileEngine::Settings engineSettings(mip::Identity(mUsername), “”, “en-US”, false);
std::vector<std::pair<std::string, std::string>> customSettings; // Create custom settings vector (pairs of strings).
customSettings.emplace_back(mip::GetCustomSettingEnableMsgFileType(), “true”); // Enable msg format for sample application testing.
engineSettings.SetCustomSettings(customSettings); // Set custom settings, then pass settings to AddEngineAsync().
Once set, you’ll be able to remove protection from MSG files.
Application Termination
New in 1.2, we’ve introduced a function called ReleaseAllResources()
. This function should be called prior to shutdown, after clearing references to all existing handlers, profiles, and engines. A sample implementation might look like:
~MyMipClass() {
profile = nullptr;
engine = nullptr;
handler = nullptr;
mip::ReleaseAllResources();
}
The pattern is similar in .NET. Prior to application shutdown, null the existing objects and call MIP.ReleaseAllResources()
.
Resources
We’ve updated the docs and samples for this release. Please submit any feedback or questions on the samples in the GitHub projects!
New API List
mip::ClassificationResult::GetSensitiveInformationDetections
mip::FileEngine::GetLastPolicyFetchTime
mip::FileEngine::GetDefaultSensitivityLabel
mip::FileEngine::GetPolicyId
mip::FileEngine::HasClassificationRules
mip::FileEngine::Settings::SetPolicyCloudEndpointBaseUrl
mip::FileHandler::GetDecryptedTemporaryFileAsync
mip::FileHandler::Observer::OnGetDecryptedTemporaryFileFailure
mip::FileHandler::Observer::OnGetDecryptedTemporaryFileSuccess
mip::File/Policy/ProtectionProfile::SetTaskDispatcherDelegate
mip::File/Policy/ProtectionProfile::SetTelemetryConfiguration
mip::HttpRequest::GetId
mip::PolicyEngine::GetLastPolicyFetchTime
mip::PolicyEngine::GetPolicyId
mip::PolicyEngine::HasClassificationRules
mip::PolicyEngine::Settings::SetCloudEndpointBaseUrl
mip::ProtectionDescriptor::GetContentId
mip::TaskDispatcherDelegate
mip::ReleaseAllResources
New Requirements and Class Updates
mip::ReleaseAllResources
must be called prior to process termination (after clearing references to all Profiles, Engines, and Handlers)mip::ExecutionState::GetClassificationResults
return type and “classificationIds” parameter has changed. ExistingExecutionState
implementations must be updated.mip::FileExecutionState::GetDataState
can be implemented by applications to specify how an application is interacting with contentIdentifiermip::HttpDelegate
interface requiresCancelOperation
andCancelAllOperations
methodsmip::HttpDelegate
interfaceSend
andSendAsync
returnmip::HttpOperation
instead ofmip::HttpResponse
mip::HttpResponse::GetBody
returnsstd::vector<uint8_t>
instead ofstd::string
mip::HttpResponse
interface requiresGetId
method implementationmip::ContentLabel::GetCreationTime
returnstd::chrono::time_point
instead ofstd::string
mip::FileEngine::CreateFileHandlerAsync
no longer accepts ‘contentIdentifier’ parametermip::FileHandler
will now throwmip::AdhocProtectionRequiredError
if ad hoc protection is required prior to applying a label.mip::HttpRequest::GetBody
returnsstd::vector<uint8_t>
instead ofstd::string
.mip::OperationCancelledError
exception is thrown when an operation has been cancelled due to shutdown or HTTP cancellation.- Telemetry component now uses the same HTTP stack as the rest of the SDK, even if the client application overrides default stack with
HttpDelegate
.
– Tom Moser