Microsoft Secure Tech Accelerator
Apr 03 2024, 07:00 AM - 11:00 AM (PDT)
Microsoft Tech Community
Microsoft Information Protection SDK for C++: Public Preview!
Published Apr 17 2018 06:27 PM 26.1K Views
Microsoft

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.

  Security and Compliance CenterSecurity 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).

 Azure Information ProtectionAzure 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

43 Comments
Copper Contributor

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? 

Copper Contributor

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.

 

 

Copper Contributor

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.

Iron Contributor

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

Copper Contributor

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

Copper Contributor

Hi Tom,

 

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

 

Error.png

Copper Contributor

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.

Brass Contributor

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.

 

Copper Contributor

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?

Copper Contributor

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

Copper Contributor

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. 

 

Copper Contributor

 

Hi @Tom Moser,

 

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

 

Thanks!

Copper Contributor

Hi,

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

Thanks

Copper Contributor

Hello team,

 

Are there any chances we might get code for Java too

Copper Contributor

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?

Brass Contributor

 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

@Deleted, 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

Copper Contributor

Hi @Tom Moser,

 

I am using the SDK to protect MS-Word documents. Like in the sample included with the SDK. However, I cannot open these encrypted files in MS-Word afterwards (getting the error "The file is corrupt and cannot be opened."). When I protect a document with the Azure RMS client in MS-Word (i.e. by clicking the button), a series of bytes is prepended to the protected document before the publishing license. These bytes are not prepended by the SDK sample, could these missing bytes be the source of the error? If so, how can I prepend them from the SDK? What is the meaning of these bytes?

 

EDIT: Using the Azure RMS SDK sample from here: https://github.com/Azure-Samples/Azure-Information-Protection-Samples/tree/master/FormFileEncrypt, I can protect a document programatically and then open it in MS-Word with no problems.

 

Thanks for your help,

Pablo Lorenceau

Microsoft

@Pablo Lorenceau are you specifying a new file as the output from the file API, or writing over the existing file? 

Copper Contributor

@Tom MoserI am writing to a new file.

Brass Contributor

Hello @Tom Moser  can you please share working example with documentation for C# version?

Microsoft

@Pablo Lorenceau it looks like you're using the RMS SDK? Have you looked at the MIP SDK? If so, can you share a snip of the code you're using to protect the file? 

 

@Kaushal Khamar The samples are available from here: https://aka.ms/mipsdksamples. We haven't published docs, yet, as the wrapper isn't yet generally available. We plan to make the docs available later this month when we GA the wrapper. 

Copper Contributor

@Tom Moser Is there have a demo to show how to get the watermark text,header and footer from a label?

Deleted
Not applicable

Dear Team,

I want to create custom C++  PoC module to use MSIP for reading/writing custom levels. But I am unable to get identity for test tenant as over its returning-  "You don’t have permission to view this form"

Please suggest how should I proceed.

 

Regards,

Abhijeet

Microsoft

Hi @Deleted , 

 

We no longer provide the test tenants as we've shipped to be generally available. You'll need to have your own tenant to test against. If you don't, the best way to get one is to sign up for an O365 E3 or greater trial via this link: https://products.office.com/en-us/try

Copper Contributor

Hi,

 

there is a way to use the samples in server side mode (whitout prompting the authentication)?

In the IPCManaged API there was "APIMode.Server".

 

Thanks

Microsoft

Yep, you can use certificate-based authentication to do this. This sample (https://github.com/Azure-Samples/mipsdk-fileapi-dotnet-onbehalfof/blob/master/README.md) covers doing it via web app with on-behalf-of auth, but something like this AAD sample would accomplish the same. You can refer to the rights listed in the sample link to see which rights the app registration requires.

 

https://github.com/Azure-Samples/active-directory-dotnet-daemon-certificate-credential

Deleted
Not applicable

Hi Tom,

I have created  a test app using mip file api, but when its trying get FileEngine object, I agtting this error-

 

libc++abi.dylib: terminating with uncaught exception of type mip::NoPolicyError: Compliance policy not configured: missing <policy> tag, correlationId:[7fff415c-1364-4901-8989-00001481f60e]
Abort trap: 6

 

Deleted
Not applicable

Hi Tom,

I have created  a test app using mip file api, but when its trying get FileEngine object, I getting this error-

 

libc++abi.dylib: terminating with uncaught exception of type mip::NoPolicyError: Compliance policy not configured: missing <policy> tag, correlationId:[7fff415c-1364-4901-8989-00001481f60e]
Abort trap: 6

Regards,

Abhijeet

Microsoft

@Deleted have you created a label policy in the security and compliance portal and added all of the labels to the policy? That portal is at https://protection.office.com.

Deleted
Not applicable

Hi Tom,

Thankyou, It worked for me.

Do we have any API in sdk to scan the document and suggest labels on  the basis of its content.

 

Thanx

Microsoft

@Deleted Not yet, but stayed tuned :)

Copper Contributor
Hello @Tom Moser, Thank you for your work. I'm now trying to develop small application for AIP in C++ for Windows. I'm now trying to list labels, but no matter if I build version from samples with token acquirement with pythopn or build my own getting tokens from powershell I'm allways getting error 204 on any request Like: file_sample.exe -l --username ****@****.onmicrosoft.com --password ******* Something bad happened: Request failed with http status code: 204, correlationId:[****] Exiting. Can you advice what can be done in this case? Error is happening on FileEngine generation: mEngine = engineFuture.get(); With no chance to debug. And one more question. I see that c++ SDK is in progress and it looks nice but community is small. So is there a reason to work with it or to move into RMS SKD on C# and to mess with CLI\CLR? Thanks in advance.
Microsoft

@OlegBulavchuk  

 

Hi Oleg, 

 

You'll need to make sure you've performed the unified labeling migration and published a label policy. The 204 is because there's no policy found.

 

https://docs.microsoft.com/en-us/information-protection/develop/faqs-known-issues#error-failed-to-pa...

 

We are encouraging our customers and partners to use MIP SDK as we won't likely make any significant future investments in RMS SDK. We do have a C# wrapper available for the MIP SDK on NuGet and are investigating adding Java support. 

 

https://www.nuget.org/packages/Microsoft.InformationProtection.File/

 

Thanks, 

Tom

Copper Contributor
@Tom Moser Thank you for you answer. I was able to read published policy when I was creating it in O365 instance. But I'm confused right now. We have Azure Information Protection with access from Azure Portal and accessibility via RMS SDK. And we have separate Office 365 Security & Compliance portal with different labels and MIP SDK connection. Does it mean that Azure Information Protection will not be supported in near future? Or will MIP SDK gain back compatibility with Azure IP?
Microsoft

When you perform the unified labeling migration (steps here), the backend databases for Office 365 and AIP merge. Office 365 becomes the store for all of the labeling information, but you'll see that changes in AIP will show in O365 Security and Compliance Center and vice-versa.

 

This migration is require to use the MIP SDK and we have no plans to make the SDK work without it. But, I think that achieves what you were looking for: Making the AIP labels available for the SDK to consume.

 

You can create labels and policies in SCC without performing the migration, but if you've deployed AIP at any point in the past, the migration is required.

 

 

Copper Contributor

Hi @Tom Moser ,

 

Do we have any working example of email decryption functionality  with the help of MIP SDK(C#)?

Thanks.

Copper Contributor

Hi,

 

I would like to use MIP file api in my Java code.

Currently, I'm using the command-line interface, and I'm authenticating with my username and password.

I'm looking for a different way to authenticate and use the api, I see that there's 'SCC token' option and other options for authenticating, i'm not sure what does it mean and where I can get this tokens.

 

Any help will be appreciated.

Thanks.

Version history
Last update:
‎May 11 2021 01:54 PM
Updated by: