MIP SDK Samples

In our Public Preview announcement, we promised details on the sample applications that are bundled with the MIP SDK binaries. These samples are a great way to try out the SDK while reviewing the source code, which is included with the binaries.

In today’s post, I’ll talk about what each of the samples is capable of and how to run them.

Included Samples

The source code for the compiled samples included with the SDK can be found in /samples. In the samples folder are five subfolders:

/auth – The bundled python script and source/header files used for authentication

/cxxopts – The cxxopts command line parser.

/file – The File API sample source

/rms – The Protection API sample source

/upe – The Policy API sample source

Prerequisites

Because ADAL for C++ isn’t available, we make use of a simple Python script for authentication. You can either provide a token directly to the samples, or you can pass the username and password on the commandline. Please make sure you’re using a test tenant with an unprivileged account as it’s quite likely your IT admins are logging command line activity and would, consequently, log any passwords passed in to executables.

An account from a specific test tenant is required. If you don’t already have a test account for the MIP SDK preview, please fill out the form to obtain one. Turnaround time is usually two business days.

Windows

Download Python 2.7 from here and install.

Ubuntu

Install Python: sudo apt-get install python

Install CPPRest: sudo apt-get install libcpprest

Install libgsf: sudo apt-get install libgsf-1-dev

Mac

Install Python: brew install python

Install libgsf: brew install libgsf

Install openssl: brew install openssl

Compiled Samples

We’ve included three compiled samples in the SDK. These samples, along with the auth.py script can be found in the ZIP file in the bins\\release\[x86 or amd64] folder.

Be sure the auth.py script is in the same directory as the executable and the path to python.exe is in your system path (typically C:\Python27 on Windows). You can quickly add it on PowerShell by running:

    $env:path += “;C:\Python27;”

For the sake of all examples below, we’ll assume that you’re already navigated to the appropriate bins directory in your OS and terminal of choice.

File API Sample – file_sample.exe

We have two ways to get the policy in the File API app – Either by pulling from the service (preferred) or by importing the included policy XML file. The import method exists only for the preview and will be removed at GA. To use the sample policy, replace –username and –password with –policy policy.xml.

A few noteworthy items:

If using the XML file, it’s not possible to read/apply/remove RMS protection. This only works with service auth enabled.

Labels applied via MIP SDK are not readable by the AIP client. This is coming in the near future.

Labels applied via the AIP client cannot be read by the SDK samples. This is also coming in the near future.

File API List Labels

For the other sample actions to be useful, we need to first list all of the labels available in our MIP policy. We can do that with the –listlabels switch.

./file_sample –username User@mippreviewtenant20.onmicrosoft.com –password “Password123” –file “PATH” –listlabels Label ID: cc9327fe-12b3-4c6c-ae27-6be52958a213 Label name: Public Label description: Data classification as ContosoCorp Public Label ID: d48d0e60-c766-40d6-96d3-53b2857fe775 Label name: General Label description: Data classification as ContosoCorp General Information

Label ID: 283068d1-5c83-412a-87d8-fdbc417ad37f Label name: Confidential Label description: Contoso Corp Data classified as confidential. Over-sharing may cause h…

Copy one of the label IDs from your output. We’ll use that in subsequent steps.

Set a Label

Copy one of the label IDs from the previous step. Create a new Word document in a directory on your test machine. Use the same auth parameters as in the previous step, but rather than list labels, specify a file (–file PATH) and a label ID (–setlabel GUID) to apply.

./file_sample –username User@mippreviewtenant20.onmicrosoft.com –password “Password123” –file “PATH” –setlabel <GUID>

This will generate a new file with _modified appended to the file name. The labeled file will have protection applied, if applicable.

Read a Label

Finally, read the label from the previously labeled document.

./file_sample –username User@mippreviewtenant20.onmicrosoft.com –password “Password123” –file “PATH” –getfilestatus

Policy API Sample – upe_sample.exe

The Universal Policy Engine sample provides an example of how UPE can expose the actions a specific label should take when chosen by an end user or selected programmatically. UPE will be primarily leveraged by applications where the user is making some choice about a file and a software engineer needs to make the application apply all appropriate settings for that label; content marking, metadata, and protection.

Policy API List Labels

Running the sample with the listLabels switch will connect to the Office 365 Security and Compliance Center (SCC) endpoint using the provided credentials, and list all labels and settings from the policy. This will not store any engines and will generate a unique engine ID each time. To store the engine information locally, use the optional –useStorageCache switch for all examples.

 ./upe_sample –username User@mippreviewtenant20.onmicrosoft.com –password “Password123” –listLabels [–useStorageCache]

A new engine is added, and the labels are displayed.

List Engines

The sample demonstrates listing all engines. Without the optional useStorageCache switch, the result will always be NO CACHED ENGINES. This is because the local cache isn’t being used.

Running the sample with listEngines and useStorageCache will use the local cache to display the IDs of all previously created policy engines for a user.

./upe_sample –listEngines –useStorageCache –username User@mippreviewtenant20.onmicrosoft.com

Load Engine

Copying one of the engine IDs from the previous example, it’s possible to load an existing engine ID from the storage cache rather than creating a new one and pulling the policy (again) from the SCC endpoint.

./upe_sample –username User@mippreviewtenant20.onmicrosoft.com –password “Password123” –listLabels –useStorageCache –engineId 207aa3b7-c1c3-4379-8e2b-0000896273d0

Note that the engine is loaded, rather than added and the app lists the available labels. The same method implemented in the sample app can be used in other applications to store engines in local cache.

Compute Action – Set a New Label

When a user or service takes an action to apply a specific label, the policy API can tell the application exactly what it should do by calling compute actions. Supplying state information to the ComputeActions method (current label, new label) returns the actions that should be taken by the application.

Copy one of the label IDs from the previous step and insert below after –newLabelId. Include the –computeActions switch.

./upe_sample –username <USERNAME> –password “Password123” –newLabelId 10611d50-8e1b-4024-a6de-f0c34527e283 –computeActions

Compute Action – Replace an Existing Label

This example is similar to the previous example but shows that two label IDs can be provided – the current label and a new label to be applied to the item. The API will return the actions that should be taken to strip off the current label and then the actions to apply the new label.

./upe_sample –username <USERNAME> –password “Password123” –newLabelId 10611d50-8e1b-4024-a6de-f0c34527e283 –oldLabelId edaf59a3-24fa-4052-9d29-077153023aa6 –computeActions

Protection API Sample – rms_sample.exe

The protection sample application demonstrates how to perform four different actions on a given input file:

Protect with ad hoc protection

Protect with a template

Unprotect a file

Show file status

While a file is used in the sample application, it should be noted that the Protection API works only on streams.

The included sample app does the following:

Read file from disk as a stream.

Generate a publishing license.

Protect the plaintext stream.

Writes the output stream to a file, where the file format is:
- Bytes 0 – 3: Size of the serialized publishing license
- Variable # of bytes: Serialized publishing license
- Remaining Bytes: ciphertext of the input stream

The sample is intended to demonstrate that the Protection API can take some plaintext input stream and generate both a publishing license (PL) and ciphertext. Once a developer has these two objects, they can then integrate the ciphertext and PL with their own proprietary file formats. Upon consuming a file with embedded protected content, an application can use the publishing license to acquire a use license for the authenticated user, if the user has rights. Upon acquisition, the UL can be used to decrypt the encrypted stream.

For a refresher on AIP certificates, review this blog post.

This file cannot be opened using any of the default viewers or tools. The stream can, however, be decrypted by the sample app.

Apply Ad Hoc Protection

The following will apply protection to TextFile.txt where Tom and Bob at Contoso will have READ only permissions. It’s also possible to pass in a specific role by using the –roles parameter. For the full list of rights and role, consult this Docs article.

./rms_sample –username <USERID> –password “Password123” –protectAdHoc –users tom@contoso.com,bob@contoso.com –rights READ –file “C:\mip\TestFiles\TextFile.txt”

Apply Template Protection

Using one of the template GUIDs from the List Templates sample, pass in credentials, client id, the protectTemplate switch, template ID, and the name of the file to protect. It will apply template-based protected to the file.

./rms_sample –username <USERID> –password “Password123” –protectTemplate –templateId <GUID> –file “C:\mip\TestFiles\TextFile.txt”

Remove Protection

If the provided user has rights, protection will be removed from the provided file.

./rms_sample.exe –username <USERID> –password “Password123” –unprotect –file ‘C:\mip\TestFiles\TextFile.txt.protected’

Show File Status

This sample will show the status of the protected file. Protection type (template or Ad-hoc), policy name, description, users, and rights.

./rms_sample.exe –username <USERID> –password “Password123” –status –file ‘C:\mip\TestFiles\TextFile.ptxt’

Wrapping it up

Our hope is that we’ve given you a good overview on how to get started with the sample apps. We encourage you to try various permuations of the parameters, apply labels and protection, remove labels and protection, etc. If you have any questions on the code, please comment here, or head over to our AIP Yammer community, sign up, and participate in the community discussion there!

Microsoft Information Protection SDK: Sample Apps