How-to: work with encryption settings

  • Article

Important

Versions of the Microsoft Rights Management Service SDK released prior to March 2020 are deprecated; applications using earlier versions must be updated to use the March 2020 release. For full details, see the deprecation notice.

No further enhancements are planned for the Microsoft Rights Management Service SDK. We strongly recommend adoption of the Microsoft Information Protection SDK for classification, labeling, and protection services.

This topic orients you to our encryption packages and shows some code snips for their use.

Support for AES 256, the new default

No additional code is required to use AES 256 based encryption as it is the new default, assuming you build against the RMS SDK 2.1 March 2015 update or later. We encourage you to seriously consider updating your applications with this release for the additional security benefits of AES 256.

Important

Support for consumption of AES 256 protected files has existed since the October 2014 release. If you are running applications built with a version of the SDK from before October 2014, this update will break your application. Please make sure that customers of the applications you are building, are either using the updated SDK, or are willing to immediately update to the most recent version of your application.

 

API encryption support

Beginning with the March 2015 update, we have incorporated the following three flags into our API and their associated encryption packages:

  • IPC_ENCRYPTION_PACKAGE_AES256_CBC4K
  • IPC_ENCRYPTION_PACKAGE _AES128_CBC4K
  • IPC_ENCRYPTION_PACKAGE _AES128_ECB (Also known as, Deprecated Algorithms)

The encryption package flags, see Preferred encryption, can be used in conjunction with the, License Property flag - IPC_LI_PREFERRED_ENCRYPTION_PACKAGE.

Following are some simple code snippets that demonstrates how to use the new license property.

Deprecated Algorithms

We are no longer exposing the IPC_LI_DEPRECATED_ENCRYPTION_ALGORITHMS flag in our API. This means that future applications will no longer compile if they reference this flag, but applications already built using it will continue to work since we honor the flag privately in the API code.

Getting the benefit of the old deprecated encryption algorithms flag can still be achieved simply by changing one flag. See the following code snippets for an examples.

Protect Files with AES 256 CBC4K

No change in code needed, AES 256 CBC4K is the default.

hr = IpcCreateLicenseFromTemplateID(pcTil->aTi[0].wszID,
                                0,
                                NULL,
                                &pLicenseHandle);

Protect Files with AES-128 CBC4K

hr = IpcCreateLicenseFromTemplateID(pcTil->aTi[0].wszID,
                                0,
                                NULL,
                                &pLicenseHandle);

DWORD dwEncryptionMode = IPC_ENCRYPTION_PACKAGE_AES128_CBC4K;

hr = IpcSetLicenseProperty(pLicenseHandle,
                        false,
                        IPC_LI_PREFERRED_ENCRYPTION_PACKAGE,
                        &dwEncryptionMode);

Protect Files with AES-128 ECB (Deprecated Algorithms)

This sample also shows the new way of supporting deprecated algorithms.

hr = IpcCreateLicenseFromTemplateID(pcTil->aTi[0].wszID,
                                0,
                                NULL,
                                &pLicenseHandle);

DWORD dwEncryptionMode = IPC_ENCRYPTION_PACKAGE_AES128_ECB;

hr = IpcSetLicenseProperty(pLicenseHandle,
                        false,
                        IPC_LI_PREFERRED_ENCRYPTION_PACKAGE,
                        &dwEncryptionMode);