File SDK email message file processing

MIP SDK supports decryption and encryption for email messages. Both .msg files, generated by Outlook or Exchange, and .rpmsg files are supported by the SDK although via slightly different methods.

Common use cases for this scenario are:

• Decrypt mail and attachments for data loss prevention (DLP) inspection.
• Publish protected messages directly from line-of-business applications
• Decrypt, modify, and re-protect messages in transit.
• Apply labels to emails from DLP or mail gateway services.

MSG File Support Statement

MIP SDK supports protection application and removal for MSG files. Given the variety of encoding types and variables in the format over the years, it's not possible to guarantee that MIP SDK can remove protection from all MSG files. The following section describes supportability for MSG files from various sources.

• Removing protection from MSG files that were protected with MIP SDK is fully supported.
• Removing protection from MSG files created by currently supported versions of the Outlook client is fully supported.
• Removing protection from MSG files created by out-of-support versions of the Outlook client is supported on a best-effort basis.
• Reprotection of MSG files is not available with protected labels. Users must unprotect and remove the protected label explicitly before protecting the file again with another label.

Labeling of MSG Files

MIP SDK supports reading and writing labels on MSG files. Child attachments don't inherit the label, but inherit the protection settings. Review Labeling and Protection Operations in the File SDK for .msg files for more details.

Labeling and Protection Operations in the File SDK for .msg files

File SDK supports labeling and protection operations for .msg files in manner identical to any other file type, except that the SDK needs the application to enable MSG feature flag.

As discussed previously, instantiation of FileEngine requires a settings object, FileEngineSettings. FileEngineSettings can be used to pass in parameters for custom settings to meet specific application needs. To enable MIP SDK to process MSG files, the CustomSettings property of the FileEngineSettings object is used to set the flag for enable_msg_file_type to enable processing of .msg files.

If you've created a FileEngineSettings object called engineSettings, you'd set this property in .NET as follows:

engineSettings.CustomSettings = new List<KeyValuePair<string, string>>();
engineSettings.CustomSettings.Add(new KeyValuePair<string, string>("enable_msg_file_type", "true"));

The .msg file protection operations pseudocode may look like:

• Set enable_msg_file_type flag in mip::FileEngineSettings and add the mip::FileEngine to mip::FileProfile.
• Use the FileEngine to fetch the list of labels for the user.
• Construct mip::FileHandler that points to the file to be labeled.
• Select a label and use the mip::FileHandler's SetLabel method to apply the label.

Refer to Quickstart: List labels for information on how to list labels.

Changing Default Attachment Handling Behaviors

By default, the File SDK attempts to process all attachments that are part of an MSG file, or a message.rpmsg file when using the inspection APIs. It doesn't recursively decrypt attachments that are part of MSG files attached to the root MSG. Modification of the default handling behavior is not supported at this time.

File SDK operations for .rpmsg files

MIP SDK exposes an inspection function that can decrypt the embedded message.rpmsg file and present a set of byte streams as output. It's up to the SDK consumer to extract the message.rpmsg file and pass it to the inspection API. Variations of this file name exist for Office Message Encryption scenarios and the API will also accept message_v2, v3, or v4 files.

Commonly, mail gateway and data loss prevention (DLP) services handle MIME compliant messages while email is in transit. When mail is protected, the encrypted contents of the message are stored in an attachment, message.rpmsg. This attachment contains the encrypted email body and any attachments that were part of the original message. The rpmsg file is then attached to a plaintext wrapper email and sent to the mail service. Once that message leaves the Exchange or Exchange Online boundary, it's in the MIME-compliant format so that it can be sent to its destination.

In most cases, the DLP service needs to get the attachments and plaintext bytes from the message to inspect and evaluate against DLP policies. The inspect API takes the message.rpmsg as input and returns byte streams as output. These byte streams contain the plaintext bytes of the message and the attachments. It’s up to the application developer to handle these streams and to do something useful with them (inspect, recursively decrypt, etc.).

The Inspect API is implemented through a class, mip::FileInspector, which exposes operations for inspecting supported file types. mip::MsgInspector which extends mip::FileInspector, exposes decryption operations specific to rpmsg file format. MIP SDK doesn't support any publishing scenarios for message.rpmsg files. Additionally, the FileHandler::RemoveProtection() API doesn't support message.rpmsg files. Message.rpmsg files can be decrypted only for inspection and will not output a valid, usable file. If your application requires a file output, you must pass in an MSG file and remove protection from that object.

mip::MsgInspector class exposes below members:

public const std::vector<uint8_t>& GetBody()
public BodyType GetBodyType() const
public BodyType GetBodyType() const
public InspectorType GetInspectorType() const
public std::shared_ptr<Stream> GetFileStream() const

For more information, see the Microsoft Information Protection (MIP) SDK for C++: Reference.

Next Steps

• Review the File SDK - Process email .msg files (C++) quickstart
• Review the File SDK - Process email .msg files (C#) quickstart