AD RMS Handles and Sessions

  • Article

[The AD RMS SDK leveraging functionality exposed by the client in Msdrm.dll is available for use in Windows Server 2008, Windows Vista, Windows Server 2008 R2, Windows 7, Windows Server 2012, and Windows 8. It may be altered or unavailable in subsequent versions. Instead, use Active Directory Rights Management Services SDK 2.1, which leverages functionality exposed by the client in Msipc.dll.]

Active Directory Rights Management Services functions use the following data types to provide opaque handles to objects. These objects are variously called sessions, bound licenses, libraries, crypto-providers, and environments.

  • DRMENVHANDLE is a handle specifically for secure environments.
  • DRMHSESSION is a handle to a client or license storage session.
  • DRMPUBHANDLE is a handle to issuance licenses, rights, and users.
  • DRMQUERYHANDLE is a handle to unbound objects within a license.
  • DRMHANDLE is a handle for everything else, including bound license objects.

Create, copy, and delete these objects with their appropriate functions. It is important to use these functions for duplicating and closing objects, so the system can maintain a correct reference count and manage resources appropriately. Also, closing a handle or session properly clears sensitive information out of memory. Closing a handle or session closes all objects within that handle, so be sure all contained objects are properly closed before closing the object. Each handle type has the following duplication and closing methods.

Handle Duplication function Closing function
DRMENVHANDLE DRMDuplicateEnvironmentHandle DRMCloseEnvironmentHandle
DRMHSESSION DRMDuplicateSession DRMCloseSession
DRMQUERYHANDLE None DRMCloseQueryHandle
DRMPUBHANDLE DRMDuplicatePubHandle DRMClosePubHandle
DRMHANDLE DRMDuplicateHandle DRMCloseHandle

 

When declaring and initializing a handle, it should be set to a special *_INVALID value, not NULL or zero, as shown here.

DRMENVHANDLE hEnv = DRMENVHANDLE_INVALID;
DRMHSESSION hSession = DRMHSESSION_INVALID;
DRMQUERYHANDLE hQuery = DRMQUERYHANDLE_INVALID;
DRMPUBHANDLE hPub = DRMPUBHANDLE_INVALID;
DRMHANDLE hHandle = DRMHANDLE_INVALID;

Similarly, when checking the value of a handle, be sure to compare it to the *_INVALID value, not NULL, as shown.

if (hEnv == DRMENVHANDLE_INVALID)
//Handle error...

The DRMHANDLE and DRMQUERYHANDLE structures are used for navigating unbound licenses. For more information, see Querying Licenses.

AD RMS Functions