Microsoft Information Protection SDK - Metadata

The Microsoft Information Protection SDK generates the set of metadata that should be applied to a file. This metadata is a representation of the label. This document describes the metadata the SDK generates to apply to mail, documents, and other records.

Labels

Labels in the Microsoft Information Protection SDK are applied to information to describe the sensitivity of that information. Label data is persisted to file or record in a set of key-value pairs that describe the label. The metadata name is built on the following structure:

DefinedPrefix_ElementType_GlobalIdentifier_AttributeName

When applied to data labeled with Microsoft Purview Information Protection, the result is:

MSIP_Label_GUID_Enabled = true

The GUID is a unique identifier for each label in an organization. An object can only have one label from the same organization. Multiple labels from the same organization can't be written to a file or object.

Microsoft Information Protection SDK Metadata

The MIP SDK applies the following set of metadata.

Attribute	Type or Value	Description	Mandatory
Enabled	True or False	This attribute indicates whether the classification represented by this set of key-value pairs is enabled for the data item. DLP products typically validate the existence of this key to identify the classification label.	Yes
SiteId	GUID	Microsoft Entra tenant ID	Yes
ActionId (Removed in MIP SDK 1.8 and later)	GUID	ActionID is changed each time a label is set. Audit logs include both old and new actionID to allow chaining of labeling activity to the data item.	Yes
Method	Standard or Privileged	Set via mip::AssignmentMethod. Standard implies that the label is applied by default or automatically. Privileged implies that the label was manually selected.	No
SetDate	Extended ISO 8601 Date Format	The timestamp when the label was set.	No
Name	string	Label unique name within the tenant. It doesn't necessarily correspond to display name.	No
ContentBits	integer	ContentBits is a bitmask that describes the types of content marking that was applied to content based on policy and client capabilities. CONTENT_HEADER = 0X1, CONTENT_FOOTER = 0X2, WATERMARK = 0X4, ENCRYPT = 0x8	No

When applied to a file, the result is similar to the table below.

Key	Value
MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_Enabled	true
MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_SetDate	2018-11-08T21:13:16-0800
MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_Method	Privileged
MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_Name	Confidential
MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_SiteId	cb46c030-1825-4e81-a295-151c039dbf02
MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_ContentBits	2
MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_ActionId	88124cf5-1340-457d-90e1-0000a9427c99

ContentBits

The contentBits metadata property in MIP SDK is used to indicate which content-modifying actions were taken on a file by the labeling application.

contentBits can be read by downstream applications to understand which actions were applied to the file. Using this property, an application like Word, Excel, or PowerPoint can compare the value on the file metadata to the value it computes based on the policy. If there's a difference, it may apply the missing information.

Take, for example, the MIP File SDK. It doesn't support applying header, footer, or watermark directly to a file. When a file is labeled with MIP SDK, the only outcomes for contentBits are 0x0 if the file is unprotected or 0x8 if the file is protected. This is true even if the label policy has header, footer, and watermark configured.

When the file is opened in Microsoft Word, the header, footer, and watermark will be missing. When the user clicks save the policy is reevaluated and contentBits on the file is compared to the policy result. If there's a difference, the application applies the missing content marking.

Note

This feature requires the Azure Information Protection client today, and works only in Word, Excel, or PowerPoint. It does not apply to Outlook.

Extending Metadata with Custom Attributes

Custom metadata may be appended via File and Policy SDK. Custom attributes must maintain the base MSIP_Label_GUID prefix.

For example, an application written by Contoso Corporation must apply metadata indicating which system generated a labeled file. The application can create a new label, prefixed with MSIP_Label_GUID. The software vendor name and custom attribute are appended to the prefix to generate the custom metadata.

LabelingOptions options = new()
{
    AssignmentMethod = AssignmentMethod.Standard
};

options.ExtendedProperties = new List<KeyValuePair<string, string>>();
options.ExtendedProperties.Add(new KeyValuePair<string, string>("GeneratedBy", "HRReportingSystem"));

MSIP_Label_f048e7b8-f3aa-4857-bf32-a317f4bc3f29_GeneratedBy = HRReportingSystem

Note

To maintain compatibility across common applications, the maximum length for each a key and a value is 255 characters.

Note

When the protected co-authoring experience is enabled, custom metadata properties will be written to the custom.xml component of supported Office file types.

Versioning

Over time, attributes will be introduced, modified, or retired. It's expected that applications continue to handle these old or retired attributes, as replacing the value across an enterprise may take years.

When replacing an attribute with a newer version, a version suffix should be added to the attribute:

MSIP_Label_GUID_EnabledV2 = True | False | Condition

Email

Metadata applied to email maintains a key/value pair format similar to that of documents. The primary difference is that all attributes are serialized in to a single email header called MSIP_Labels. The key/value pairs are delimited by a semicolon and a whitespace, and placed in the new header.

Using the sample metadata above:

MSIP_Labels: MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_Enabled=true; MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_SetDate=2018-11-08T21:13:16-0800; MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_Method=Privileged; MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_Name=Confidential; MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_SiteId=cb46c030-1825-4e81-a295-151c039dbf02; MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_ContentBits=2; MSIP_Label_2096f6a2-d2f7-48be-b329-b73aaa526e5d_ActionId=88124cf5-1340-457d-90e1-0000a9427c99