Home
Microsoft

Microsoft Information Protection SDK for C++: Public Preview!

Welcome!

Today we're proud to announce the Microsoft Information Protection SDK Preview!

The Microsoft Information Protection SDK (MIP SDK) brings the classification, labeling, and protection capabilities of Azure Information Protection and Office 365 Security and Compliance Center in to a simple, lightweight, cross-platform software development kit that enables any application to read and apply MIP labels and protection.

 

In this release, we’re providing our first look at the components of the SDK and how your organization will be able to use each of them to make your own applications Microsoft Information Protection enabled and fully aware.

 

What is Microsoft Information Protection?

Back in February, over on the Enterprise Mobility + Security blog, we revealed details on the Microsoft Information Protection story and the work we’re doing to bring together Azure Information Protection and Office 365 labeling via Security and Compliance Center.

  SCC.pngSecurity and Compliance Center

It's likely that if you're an existing Office 365 or Azure Information Protection user, you're familiar with Security and Compliance Center (above) and/or the AIP labeling bar (below).

 Bar.PNGAzure Information Protection

Microsoft Information Protection is the combination of AIP and the O365 labeling in Security and Compliance center, and the future integration around the labeling experience that will come as part of O365 and EMS. The videos below cover some of the changes we’re making as we work toward this goal.

 

Azure Information Protection: Unified labeling, on-prem scanning and protection across platforms

Preparing for GDPR: Compliance management and information protection capabilities in Microsoft 365

 

 

As the classification, labeling, and protection experience becomes native across the Office 365 experience, your organization and users will begin to demand that the ease-of-use they experience in their Office applications and services carry over to 3rd party and line-of-business applications. As our customers and partners, you’ll be able to use the MIP SDK to make classification, labeling, and protection in these applications easier than ever.

 

File, Policy, and Protection APIs

The MIP SDK is made up of three separate APIs: File API, Policy API, and Protection API.

 

Policy API

The Policy API exists to allow developers to perform label-driven actions in their applications. The typical consumer of this API will be an application owner. This API doesn’t apply a label to a document or take any action at all. Rather, it informs the application of the available labels for the current user and what actions should be taken when that label is applied. It’s up to the software engineer to code the appropriate behavior in the application and to write those changes to the output file.

For example, if I’m a software developer at a company writing a CAD/CAM application, I would leverage the Policy API to:

 

  • Display the labels available to the authenticated user.
  • Calculate the actions to take when a label is selected, either by a user or programmatically.
  • Calculate the actions to take when a label is

 

Protection API

The Protection API enables developers to read and write Azure Information Protection rights-managed streams. The API can be used to read encrypted input and decrypt to reason over the contents in plaintext, or to take plaintext output from a system and encrypt it in an AIP rights-managed format.

We believe that organizations using RMS SDK 2.1 or 4.2 will be able to fully replace that functionality with the Protection API capabilities from the MIP SDK.

 

File API

Last, but certainly not least, is the File API. The file API provides an easy-to-use method of performing several file related tasks for well-known file formats. By simply passing in a label ID, the API can apply a label, content marking, and protection to a list of supported formats. Additionally, labels can be fetched from the service, read from a file, deleted or changed, and justification provided when downgrading the label.

The File API isn’t truly independent. Rather, it provides an abstraction of the previous APIs so that developers don’t need to worry about handling policy actions or protection actions; the File API, based on the labels that are present, knows exactly what to apply and how to apply it to the supported file types.

 

Use Cases 

Before embarking on any journey with a new SDK, we understand that it’s important to have solid use cases and business justification. We’ve been mulling over the various use cases for the SDK for quite a long time. You’ll be able to use some of our ideas below to kickstart discussions in your own business.

From the standpoint or Microsoft and the MIP SDK team, our #1 goal with the SDK is this:

The Microsoft Information Protection SDK will enable our third-party ISV ecosystem to build native support for MIP classification, labeling, and protection in to their applications.

One of the most common questions we hear on the Information Protection teams is:

 

“When will Microsoft support application or service X with MIP?”

 

It’s extraordinarily difficult to build a solution that works across many applications, in a scalable, fast, user friendly, and most important, transparent manner. We believe that the best MIP CLP experience is a native application experience. We’ll be announcing several partnerships with security ISVs this week at RSA Conference and as we approach GA. These partners are already committed to building support for MIP in to their applications and services.

 

 

File API Use Cases

We believe that, for most tasks, organizations will build functionality that leverages the File API. Because the API can be used to read, apply, or remove labels and protection, without having to worry about modifying the file contents in your own code, it’ll be the simplest, most common approach to using the SDK. Here are some examples of File API use cases:

 

  • You’re a software engineer at a financial services institution. You want to be sure that data from your LOB applications, typically exported in Excel format, are labeled on export based on the contents. File API can be used to list available labels then to apply the appropriate label to a supported file format.

 

  • Your company develops a cloud access security broker (CASB). Your customers ask for the ability to apply MIP labels to Microsoft Office and PDF documents. The File API would enable you to display a list of configured labels, then allow your customers to build rules which would apply the desired label. File API, taking in the label ID, would handle the rest for files meeting the customer’s criteria.

 

  • Your company provides a service-based data loss prevention solution and/or a CASB that monitors SaaS applications for file activity. To reduce the risk of data loss or exposure where data is protected with MIP, your service must be able to scan the contents of protected files. Using File API for the supported formats, when the service is a privileged user, you can remove protection, scan the contents for restricted or sensitive content, discard the plaintext result, and apply a service rule to report on or remediate the risk if found.

 

Policy API Use Cases

The Policy API provides functionality that allows application developers to expose to their applications the labels that are available within a tenant and to compute the actions that the label should take. Everything that comes after, applying marking, metadata, protection, etc. is up to the developer to implement. Examples of some policy API use cases are:

 

  • Your company develops 3d design software that uses a proprietary file format. Your customers use MIP and want to be able to apply labels natively through your application. As the software engineer, you’d use the Policy API and a custom control to display the labels available for the authenticated user. Once the user selects a label, you’d call the compute action method of the API to know exactly what should be applied as far as metadata, content marking, and protection.
  • Your company develops a DLP service that allows your customers to configure DLP policies via a central administration portal. You have customers that use Microsoft Information Protection and would like to be able to read or apply AIP labels as part of DLP policies. As the software engineer, you can use the Policy API to get a list of labels for the customer organization, then read those labels as part of a DLP rule or apply the label information as part of a rule action.

 

Protection API Use Cases

 

  • Your company develops 3d printing software using a propriety file format. You want to use AIP to protect the file, so it can be printed only by specific users. Using the Protection API, you can apply protection to the file so that only authorized consumers would be able to open, and/or print. It would even be possible to grant some users the ability to view while restricting the right to print.

 

  • Your company develops an eDiscovery solution that processes Exchange mailboxes and PST files. Your application must be able to user to decrypt messages to fully perform eDiscovery. Using a custom message/RPMSG parser and a sufficiently privileged account, you could leverage the RMS API to decrypt the encrypted file, scan the contents, and discard if out of scope or package if in scope.

 

  • Your company provides a service-based data loss prevention solution and/or a CASB that monitors SaaS applications for file activity. To reduce the risk of data loss or exposure in data protected with MIP, your service must be able to scan the contents of protected files. Using Protection API for formats not supported by File API, you can enable your service to decrypt the protected information (assuming the service has rights), analyze the plaintext contents, discard securely, and apply a service rule to report on or remediate the risk if found. Data which was unable to be decrypted by the service could then be blocked outright.

SDK Binaries

The preview release of the SDK can be found here: https://aka.ms/mipsdkbinaries

Inside the ZIP file, you’ll find:

  • Bins: The compiled binaries for Linux, MacOS, and Windows. The compiled sample apps are also included in the Bins\<OS> path.
  • Include: MIP SDK C++ headers
  • Samples: Source code for the SDK sample applications.

Documentation

 

Get Started Today!

Our next posts will dive more in to the fundamentals of the SDK from a developer’s point of view, as well as in to our sample and tutorial code. In the meantime, if you're looking to get started with writing your own C++ app with the SDK, you'll need to obtain a user identity from one of our test tenants that has the necessary Security and Compliance Center flights enabled. Some items to note:

  • This user identity is in a test tenant and will be shared across all preview participants.
  • We require a valid, verifiable corporate email domain.
  • We will be monitoring the accounts for abuse and reserve the right to revoke access at any time and without notice.

If you’re interested in getting started with the sample apps and starting to build your own integration, please fill out this form to start the process. We reply with an account within two business days (Future Note: This process will only exist until the necessary service components are in public preview).

 

Kartik and I are both at RSAC this week, so if you have questions, want to see a demo, or just want one of our new stickers, stop by the Microsoft Information Protection booth in the expo!

 

Tom Moser, @milt0r, Sr. Program Manager – Azure Information Protection

Kartik Kanakasabesan, @kkanakas , Principal Program Manager – Azure Information Protection

22 Comments

Hi, looking forward to using this library. Will there come a C# library (for Windows at least) as well or will C++ only be supported?

I tried reading the AIP classification from docx AIP classified file using the file_samp.exe file on a Windows system but got the error below. Is it supposed to fail like this?

file_sample -f AIP_Classified.docx --username <username> --password <password>
Something bad happend: Failed API call: profile_add_engine_async Failed with: [class mip::XmlParserException] Tag not found : policy, NodeType: 15, Name: No Name Found, Value: , Ancestors: <SyncFile><Content>, correlationId:[2140e437-68f4-44e3-805d-00000e9c47bb]
Exiting.

Microsoft

Hi Niklas! 

 

We will ship a C# version soon. I don't have a date quite yet, but work is in progress!

 

Just for clarification, you used the file_sample.exe application to set a label, then attempted to read it with the app and it failed? What happens if you specify the -g switch to read the label? 

Thanks! That is great with a C# library.

 

I set the classification label in Word using the AIP toolbar on a docx file. I then tried to read the label using the MIP_SDK_Public_Preview\bins\win32\release\x86\file_sample.exe. 

 

Running the -g switch on the file gives:

Something bad happend: Failed API call: profile_add_engine_async Failed with: [class mip::XmlParserException] Tag not found : policy, NodeType: 15, Name: No Name Found, Value: , Ancestors: <SyncFile><Content>, correlationId:[12e17247-afc1-4b8d-ac69-0000176cce68]
Exiting.

Microsoft

Ah, I see. The current AIP classification experience with the bar doesn't work with the MIP SDK. You'll need to make sure you're applying the label via the SDK, which means either your own application or the sample application. I'll have a blog published next week that details the sample apps. But, the flow would be:

 

- Use File_Sample to list the available labels. Copy the GUID

- Apply that label to a file

- Read that label from the file with the -g switch

 

Also, if you haven't, you'll need to fill out the form listed in the blog to obtain a private preview account. I should have those mailed out in the next couple of days.

 

 

Thanks, it would be interesting to hear a time line for when the MIP SDK will be able to read classification labels set by AIP. It certainly sounds like it would be able to do that from the description of the library below :) Maybe the key distinction here is MIP labels opposed to AIP labels.

 

The Microsoft Information Protection SDK (MIP SDK) brings the classification, labeling, and protection capabilities of Azure Information Protection and Office 365 Security and Compliance Center in to a simple, lightweight, cross-platform software development kit that enables any application to read and apply MIP labels and protection.

Great job on making this SDK available! Looking forward to the C# version! 

Occasional Visitor

Hi,

I want to know how to get all labels in my test environment.

Run cmd.exe to execute

C:\MIP_SDK_Public_Preview\bins\win32\debug\amd64>file_sample.exe --username *** --password ***  --listlabels  --policy .\policy.xml

Specify policy.xml which contains ready-made labels, all labes show.

How will I get policy.xml and labels in my test environment?

 

C:\MIP_SDK_Public_Preview\bins\win32\debug\amd64>file_sample.exe --username *** --password ***--exportpolicy c:\1.


C:\MIP_SDK_Public_Preview\bins\win32\debug\amd64>upe_sample.exe --username *** --password ***--clientId *** --listLabels

 

throw errors below.

 

failed1.PNG

Microsoft

@Lipu Tian are you using your own environment? I don't recall seeing your name on my list of requests for a test account. The SDK today requires that you use one of our Office 365 private preview tenants to pull the policy. If you'd like one of those accounts, head to this form and sign up! I'll get you an account within a day or two.

 

https://aka.ms/mipsdkpreviewaccount

Regular Visitor

Hi Tom,

 

I tried the below command using tenant credentials and got the below error. Can I know on next steps?

 

Error.png

Regular Visitor

Hi Tom,

 

I have following Queries on labeling using MIP SDK.

1. Can we label any flat file like .txt, .log, .dat etc.? or we can label only Microsoft office files (like .docx/.ppt etc).

2. Do we have an option to watermark a document using protection api along with document protection.

Senior Member

Hi @Tom Moser,

 

Hope, You are well !!

 

We have the requirement to use this feature in custom application.

So, May I know when Microsoft will provide the Microsoft Information Protection SDK or any update on this? 

 

Microsoft

Hi Dipen! We are in public preview now and targeting general availability in late Q3 or early Q4.

 

Frequent Visitor

Hi @Tom Moser,

 

We are looking to build an integration with the classification capabilities AIP.  Is this C++ SDK the only means to integrate with it or is there an underlying REST API or similar that can be used directly?

Occasional Visitor

Hi Team,

 

Now that the MIP is in public preview now. May I use our own test account of our own environment instead of Office 365 private preview tenants?

 

Thanks,

Kewang

Occasional Visitor

Hi Team,

 

I tried to list the labels using the account of Office 365 private preview tenants, but I got the following exception. Any suggestions?

 

exception.png

 

Thanks,

Kewang

Microsoft

Hi @Kathy Church

 

We won't be exposing any REST APIs as part of the SDK, at least in the near term. All operations will be performed via the C++ APIs. 

 

Occasional Visitor

 

Hi @Tom Moser,

 

Do you have any approximate date of the C# version release?

 

Thanks!

Occasional Visitor

Hi,

Is there any update on when these APIs will become available for general use (not just your test tenants!)?

Thanks

Visitor

Hello team,

 

Are there any chances we might get code for Java too

Regular Visitor

Hi Team,

I tried to list the labels using the account of Office 365 private preview tenants in Mac (version details and steps listed below), but I got the following exception. Any suggestions?

 

dyld: Library not loaded: @rpath/AriaOsXObjC.framework/Versions/A/AriaOsXObjC

Referenced from: /Users/****/*****/MIP_SDK_Public_Preview_September_Release/mip_sdk_upe_macos_0.4.456.0/bins/debug/x86_64/libmip_upe_sdk.dylib
Reason: image not found
Abort trap: 6

 

Mac Version and steps followed

Mac Version : macOS High Sierra 10.13.6

I didn't find instructions for Mac in the how-to-build-and-run.txt

Here are the steps I followed:

Installed 2.7 Python via brew.

Installed libgsf via brew.

Installed openssl via brew.

 

Post that moved to samples directory under mip_sdk_upe_macos_0.4.456.0 and did the following in terminal

  • scons --help
  • scons arch=x64 configuration=debug

Moved to mip_sdk_upe_macos_0.4.456.0/bins/debug/

  • ./upe_sample --username ******** --password "******" --listLabels

I'm seeing the above mentioned exception for not just upe but for also file and protection sample. Can someone help me out here?

Senior Member

 Hi @Tom Moser

 

I am pleased that MIP is generally available now.
Can you please let us know, when MIP SDK c# version is published for general availability?
Currently i am seeing that published newer version is for c++ only.

Can you please share link of demo that we can use c++ API in C# code with console application?

 

Thanks,

Dipen Shah

Microsoft

@Dipen Shah, the C# wrapper won't GA until Q1 next year. 

 

The preview version is published at https://aka.ms/mipsdkbins.

 

I've written a sample ASP.NET web application that you can use. Additionally, the download contains a sample. 

 

https://github.com/tommoser/Ignite-HOL-4000