Microsoft Information Protection SDK - Cache storage

The MIP SDK implements a SQLite3 database for maintaining SDK cache storage. Prior to version 1.3 of the Microsoft Information Protection SDK, only two types of cache state storage were supported: On disk and in memory. Both of these types stored certain data, specifically licenses for protected content and policy information, in plaintext.

To improve the security posture of the SDK, we added support for a second type of on disk cache that uses platform-specific cryptographic APIs to protect the database and its contents.

The application defines the cache type when loading the profile as part of the FileProfileSettings, PolicyProfileSettings, or ProtectionProfileSettings objects. The cache type is static for the life of the profile. Changing to a different type of cache storage type requires destroying the existing profile and creating a new one.

Cache storage types

Starting in MIP SDK release 1.3, the following storage cache types are available.

Type	Purpose
InMemory	Maintains the storage cache in memory in the application.
OnDisk	Stores the database on disk in the directory provided in the settings object. The database is stored in plaintext.
OnDiskEncrypted	Stores the database on disk in the directory provided in the settings object. The database is encrypted using OS-specific APIs.

Each engine generated by the application generates a new encryption key.

You set cache storage in one of the profile settings objects, through the mip::CacheStorageType enum.

FileProfile::Settings profileSettings(mMipContext,
    mip::CacheStorageType::OnDiskEncrypted, // Define the storage type to use.
    mAuthDelegate,
    std::make_shared<sample::consent::ConsentDelegateImpl>(),
    std::make_shared<FileProfileObserver>());

When to use each type

Cache storage is important for maintaining offline access to previously decrypted information, and ensuring performance for decryption operations when data was previously consumed.

• In Memory Storage: Use this storage type for long-lived processes where persisting the policy or license cache information across service restarts is not required.
• On Disk: Use this storage type for applications where processes might frequently stop and start, but must maintain policy, license, and service discovery cache across restarts. This storage cache type is plaintext, so is better suited for server workloads where users won't have access to the state storage. Examples of this would be a Windows service or Linux daemon running on a server, or a SaaS application where only service admins would have access to the state data.
• On Disk and Encrypted: Use this storage type for applications where processes might frequently stop and start, but must maintain policy, license, and service discovery cache across restarts. This storage cache is encrypted, so is better suited for workstation applications where a user might browse and discover the state database. The encryption helps to ensure that prying users won't have access to the policy contents or protection license content in plain text. In all cases, the data is encrypted with keys that the user can access. A skilled adversary is able to decrypt the cache with minimal effort, but this does prevent tampering and browsing.

Supported platforms for encryption

Platform	Version	Notes
Microsoft Windows	Windows 11, Support version of Windows Server
macOS	High Sierra and later
Ubuntu Linux	22.04 and later	Requires SecretService and LinuxEncryptedCache feature flag.
Android	Android 7.0 or later
iOS	All supported versions

While the MIP SDK does support other Linux distributions, we didn't test the cache encryption on RedHat Enterprise Linux, CentOS, or Debian.

Note

You set the feature flag to enable cache storage on Linux with mip::MipConfiguration::SetFeatureSettings()

Cache storage database tables

The MIP SDK maintains two databases for cache. One is for the Protection SDKs, and maintaining protection state details. The other is for the Policy SDKs and maintaining policy details and service information. Both are stored in the path defined in the settings object, under mip\mip.policies.sqlite3 and mip\mip.protection.sqlite3.

Note

The MIP SDK doesn't guarantee compatibility across different versions of its cache. Clear all files within the mip\ directory, or any alternative directory changed from default setting, before you upgrade the application to a new version of the MIP SDK.

Protection database

Table	Purpose	Encrypted
AuthInfoStore	Stores authentication challenge details.	No
ConsentStore	Stores consent results for each engine.	No
DnsInfoStore	Stores DNS lookup results for Protection operations	No
EngineStore	Stores engine details, associated user, and custom client data	No
KeyStore	Stores symmetric encryption keys for each engine.	Yes
LicenseStore	Stores use license information for previously decrypted data.	Yes
SdInfoStore	Stores service discovery results.	No

Note

The LicenseStore cache requires an identity to be set on the protection engine or file engine.

Policy database

Table	Purpose	Encrypted
KeyStore	Stores symmetric encryption keys for each engine.	Yes
Policies	Stores label policy information for each user.	Yes
PoliciesUrl	Stores backend policy service URL for specific user.	No
Sensitivity	Stores classification rules for a specific user policy.	Yes
SensitivityUrls	Stores backend sensitivity policy service URL for specific user.	No

Database size considerations

The database size depends on two factors: The quantity of engines being added to the cache and the quantity of protection licenses that were cached. Starting in MIP SDK 1.18, you can use DeleteStoredData() on ProtectionEngine to remove cached engine data programmatically. For earlier versions, an external process might be required to remove the cache if it grows larger than is desired.

The most significant contributor to database growth will be the protection license cache. If licensing caching isn't required, either because the service round trips won't impact your application performance, or the cache might grow too large, you can disable the license cache. To do so, set CanCacheLicenses on the FileProfile::Settings object to false.

FileProfile::Settings profileSettings(mMipContext,
    mip::CacheStorageType::OnDiskEncrypted,
    mAuthDelegate,
    std::make_shared<sample::consent::ConsentDelegateImpl>(),
    std::make_shared<FileProfileObserver>());

profileSettings.SetCanCacheLicenses(false);

Caching engines

In MIP SDK, an engine is created for each user performing any authenticated operation. Engines provide an interface for all operations that are performed on behalf of an authenticated identity. As discussed in Profiles and Engines concepts, FileEngine, PolicyEngine, or ProtectionEngine each has two states CREATED and LOADED. An engine needs to be created and loaded for it to be able to perform SDK operations. If an engine is not in use, the SDK caches the engine and retains it in CREATED state as long as possible depending on available resources. Each Respective SDK's profile class also provides a method UnloadEngineAsync to achieve this explicitly.

Each engine has a unique identifier id that is used in all engine management operations. The client application can provide an id explicitly, or the SDK can generate one, if it's not provided by the application. If a unique identifier is provided using engine settings objects at the time of engine creation, and caching is enabled in API profile as described above, same engines can be used every time the user performs an operation with the SDK. Follow the code snippets for creating a [mip::FileEngine](./concept-profile-engine-file-engine-cpp.md#create-file-engine-settings), [mip::PolicyEngine](./concept-profile-engine-policy-engine-cpp.md#implementation-create-policy-engine-settings).

Failing to provide an existing engineId will result in extra service round trips to fetch policy and will fetch licenses that might have already been cached for the existing engine. Caching the engine ID allows the SDK offline access to previously decrypted information and general performance improvements.

Next steps

Next, learn more about Profile and Engine object concepts to understand how to properly set MIP engine IDs to properly use MIP SDK caching.