Skip to content

Latest commit

 

History

History
77 lines (51 loc) · 5.93 KB

concept-email.md

File metadata and controls

77 lines (51 loc) · 5.93 KB
Raw
title description author ms.service ms.topic ms.date ms.author
How to - process email messages using MIP SDK
This article will help you understand the scenario of how to use MIP File SDK to process .msg and .rpmsg files.
msmbaldwin
information-protection
conceptual
04/08/2020
mbaldwin

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.

Labeling of MSG Files

Starting in MIP SDK 1.10, reading and writing labels on MSG files is supported. Child attachments will not inherit the label, but will inherit the protection settings. Review Labeling and Protection Operations in the File SDK for .msg files for additional 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 mip::FileEngine requires a settings object, mip::FileEngineSettings. mip::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.

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.

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.

Important

The inspection API does not provide an output that will result in a usable file, nor does it allow you to re-protect the input file. It outputs streams of bytes that your application can then process further. Recreating MSG files from message.rpmsg files is not supported by MIP SDK.

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 does not support any publishing scenarios for message.rpmsg files. Additionally, the FileHandler::RemoveProtection() API does not 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 details refer to API reference.

Next Steps