Microsoft Information Protection SDK - profile and engine object concepts

Profiles

The MipContext class stores SDK-specific settings. The profile is the root class for all MIP labeling and protection-specific operations in the MIP SDK. Before using any of the three API sets, the client application must create a profile. The profile, or other objects added to the profile, perform future operations. Use only one profile object per process. Creating more than one might result in unexpected behavior.

The MIP SDK has three types of profile:

The API that the consuming application uses determines which profile class to use.

The profile itself provides the following functionality:

  • State storage: Defines whether to load state in memory or persist it to disk, and whether to encrypt the state if persisted to disk.
  • Consent delegate: Defines the mip::ConsentDelegate to use for consent operations.
  • File profile observer: Defines the mip::FileProfile::Observer implementation to use for asynchronous callbacks for profile operations.

Profile settings

  • MipContext: The MipContext object that was initialized to store application info, state path, etc.
  • CacheStorageType: Defines how to store state: In memory, on disk, or on disk and encrypted.
  • consentDelegate: A shared pointer of class mip::ConsentDelegate.
  • observer: A shared pointer to the profile Observer implementation (in PolicyProfile, ProtectionProfile, and FileProfile).
  • applicationInfo: A mip::ApplicationInfo object. Information about the application that consumes the SDK and matches your Microsoft Entra application registration ID and name.

Engines

The File, Policy, and Protection SDK engines provide an interface for operations performed by a specific identity. Add one engine to the profile object for each user or service principal that signs in to the application. You can perform delegated operations by using mip::ProtectionSettings and the file or protection handler. For more information, see the protection settings section in the FileHandler concepts.

The SDK has three engine classes, one for each API. The following list shows the engine classes and a few of the functions associated with each:

  • mip::ProtectionEngine
  • mip::PolicyEngine
    • ListSensitivityLabels(): Gets the list of labels for the loaded engine.
    • GetSensitivityLabel(): Gets the label from existing content.
    • ComputeActions(): Provided with a label ID and optional metadata, returns the list of actions that should occur for a specific item.
  • mip::FileEngine
    • ListSensitivityLabels(): Gets the list of labels for the loaded engine.
    • CreateFileHandler(): Creates a mip::FileHandler for a specific file or stream.

To create an engine, pass in a specific engine settings object that contains the settings for the type of engine to create. The settings object allows the developer to specify details on the engine identifier, the mip::AuthDelegate implementation, locale, custom settings, and other API-specific details.

Engine states

An engine can have one of two states:

  • CREATED: Created indicates that the SDK has enough local state information after calling the required backend services.
  • LOADED: The SDK has built the required data structures for the engine to be operational.

An engine must be both created and loaded to perform any operations. The Profile class exposes a few engine management methods: AddEngineAsync, DeleteEngineAsync, and UnloadEngineAsync.

The following table describes the possible engine states, and which methods can change that state:

Engine state NONE CREATED LOADED
NONE AddEngineAsync
CREATED DeleteEngineAsync AddEngineAsync
LOADED DeleteEngineAsync UnloadEngineAsync

Engine ID

Each engine has a unique identifier, id, used in all engine management operations. The application can provide an id. If the application doesn't provide one, the SDK can generate it. All other engine properties, such as the email address in the identity info, are opaque payloads for the SDK. The SDK doesn't perform logic to keep any other properties unique or enforce other constraints.

Important

Use an engine ID unique to the user, and use that engine ID each time the user performs an operation with the SDK. If you don't provide an existing, unique engine ID for a user or service, the SDK makes extra service round trips. These service round trips might result in performance degradation and throttling.

// Create the FileEngineSettings object
FileEngine::Settings engineSettings(mip::Identity(mUsername), // This will be the engine ID. UPN, email address, or other unique user identifiers are recommended. 
													          mAuthDelegate,            // authDelegate implementation 
													          "",                       // ClientData
													          "en-US",                  // Client Locale
                                    false);                   // Load Sensitive Information Types

Engine management methods

The SDK has three engine management methods: AddEngineAsync, DeleteEngineAsync, and UnloadEngineAsync.

AddEngineAsync

This method loads an existing engine, or creates one if one doesn't already exist in local state.

If the application doesn't provide an id in FileEngineSettings, AddEngineAsync generates a new id. It then checks to see if an engine with that id already exists in local storage cache. If it does, it loads that engine. If the engine does not exist in local cache, a new engine is created by calling the necessary APIs and backend services.

In both cases, if the method succeeds, the engine is loaded and ready to use.

DeleteEngineAsync

Deletes the engine with the given id. All traces of the engine are removed from the local cache.

UnloadEngineAsync

Unloads the in-memory data structures for the engine with the given id. The local state of this engine remains intact, and you can reload it with AddEngineAsync.

This method allows the application to be judicious about memory usage, by unloading engines that aren't expected to be used soon.

Next steps

  • Last updated on