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
Support for Protected Coauthoring
When co-authoring for files encrypted with sensitivity labels is enabled, the label metadata storage location and format for Word, Excel, and PowerPoint files change.
When the co-authoring feature is enabled, the SDK automatically reads and writes information to and from the updated metadata storage location. If label metadata doesn't exist in the new location, the SDK will attempt to read the metadata from the legacy storage location. If found, the label is available via get label operations. The next time a set label operation is performed, the metadata is written to the updated LabelInfo locations.
The purpose of the properties as previously described doesn't change.
The following references describe the format and storage locations:
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