AD RMS Functions

  • 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.]

The Active Directory Rights Management Services (AD RMS) SDK provides the following functions, grouped by use.

Environment Management and Setup

To use the AD RMS infrastructure, the client computer and the Active Directory user account must be activated. Your application also must acquire handles to a secure environment, a client session, a license storage session, and more.

Function Description
DRMActivate Obtains a lockbox for a machine certificate or a rights account certificate for a user.
DRMCheckSecurity Performs a security check on all or part of the environment.
DRMCloseSession Closes a client session.
DRMCreateClientSession Creates a client session, which hosts license storage sessions and allows activation and other functions.
DRMCreateLicenseStorageSession Creates a license storage session, which is used in activation and other function calls.
DRMDuplicateSession Duplicates a client or license storage session.
DRMGetClientVersion Returns the version number of the Active Directory Rights Management Services client software and whether the hierarchy is for Production or Pre-production purposes.
DRMGetEnvironmentInfo Returns information about a secure environment.
DRMGetIntervalTime Retrieves the number of days from issuance that can pass before an end–user license must be renewed.
DRMGetOwnerLicense Retrieves from memory an issuance license created by a call to the DRMGetSignedIssuanceLicense function with the DRM_OWNER_LICENSE_NO_PERSIST flag set.
DRMGetProcAddress Returns the address of a function in a library. DRMGetProcAddress is the secure version of the GetProcAddress function.
DRMGetSecurityProvider Retrieves the path to a lockbox file used in DRMInitEnvironment.
DRMGetServiceLocation Retrieves the URL of a server that can perform various AD RMS services, such as computer and user activation or license acquisition.
DRMInitEnvironment Creates a secure environment for all other rights management functions to use.
DRMIsActivated Indicates whether the current user or machine is activated.
DRMIsWindowProtected Indicates whether a window is associated with a protected environment.
DRMLoadLibrary An authenticated method for loading DLLs.
DRMRegisterContent Allows the AD RMS system to keep a reference count of open AD RMS-protected documents. When the reference count is greater than zero, print screen is not enabled in all applications.
DRMRegisterRevocationList Registers a rights revocation list on the client.
DRMRegisterProtectedWindow Registers a window in the protected environment.
DRMRepair Repairs a client computer by deleting certificates previously created for the computer or user.
DRMSetIntervalTime Specifies the number of days from issuance that can pass before an end–user license must be renewed.
DRMSetGlobalOptions Sets the transport protocol to a specified value and optionally specifies whether the AD RMS server lockbox is used.

 

Issuance License Creation and Property Setting Functions

The following functions are used to create an issuance license and to specify or retrieve information in the license.

Function Description
DRMAcquireIssuanceLicenseTemplate Retrieves license templates from a server.
DRMAddRightWithUser Adds a right tied to a specific user.
DRMClearAllRights Clears the rights from an existing issuance license.
DRMCreateIssuanceLicense Creates an issuance license from scratch or from a template.
DRMCreateRight Creates an XrML right that will define the rights granted to a user or group.
DRMCreateUser Creates a user object that will be assigned a right.
DRMGetApplicationSpecificData Retrieves a name-value pair of arbitrary application-specific information.
DRMGetIssuanceLicenseInfo Retrieves information about a prototype issuance license.
DRMGetIssuanceLicenseTemplate Obtains a template from an issuance license.
DRMGetMetaData Retrieves metadata about the content that the issuance license is associated with.
DRMGetNameAndDescription Retrieves information about a specific certificate in an issuance license chain.
DRMGetRevocationPoint Retrieves a URL where a revocation list for a license can be obtained.
DRMGetRightExtendedInfo Retrieves custom name-value pairs attached to a right.
DRMGetRightInfo Retrieves information about a previously created right.
DRMGetSignedIssuanceLicense Acquires a signed issuance license online or offline, or produces an unsigned license that can be signed later.
DRMGetSignedIssuanceLicenseEx Acquires a signed issuance license offline, using a specified client licensor certificate (CLC) and rights account certificate (RAC).
DRMGetUsagePolicy Gets a usage policy that requires, or denies, access to a right based on application name, version, or other application characteristics.
DRMGetUserInfo Retrieves information about a user object.
DRMGetUserRights Retrieves user/right pairs from a prototype issuance license.
DRMGetUsers Retrieves a specific user from the issuance license.
DRMSetApplicationSpecificData Allows an issuance license to store arbitrary name-value pairs for use by the content-consuming application.
DRMSetMetaData Stores metadata about content associated with the issuance license.
DRMSetNameAndDescription Specifies the content name and description in the issuance license in several (human-readable) languages.
DRMSetRevocationPoint Sets a refresh rate and a location to obtain a revocation list.
DRMSetUsagePolicy Sets a usage policy that requires, or denies, access to a right based on application name, version, or other application characteristics.

 

Handle Functions

AD RMS functions use handles to represent objects. You should create, copy, and delete these handles by using the appropriate function, so the system can maintain a correct reference count and manage resources appropriately. For more information, see AD RMS Handles and Sessions.

Function Description
DRMCloseEnvironmentHandle Closes an environment handle.
DRMCloseHandle Closes libraries, environments, and other miscellaneous bound license objects of the DRMHANDLE type.
DRMClosePubHandle Closes a previously created DRMPUBHANDLE.
DRMCloseQueryHandle Closes a handle to an unbound license object.
DRMDuplicateEnvironmentHandle Creates a copy of an environment handle.
DRMDuplicateHandle Duplicates a handle.
DRMDuplicatePubHandle Used to copy a DRMPUBHANDLE.

 

Unbound License Navigation

You can use the following functions to navigate the underlying XrML of a license in an object-oriented fashion. These functions makes it easier to create, retrieve, and modify rights, conditions, users, and other XrML structures.

Function Description
DRMGetUnboundLicenseAttribute Retrieves an unbound license attribute from the underlying XrML.
DRMGetUnboundLicenseAttributeCount Retrieves the number of occurrences of an attribute within an object in an unbound license.
DRMGetUnboundLicenseObject Retrieves an object of a specified type in an unbound license.
DRMGetUnboundLicenseObjectCount Counts the instances of an object within a given branch of the license.
DRMParseUnboundLicense Creates a handle to an unbound license, to allow an application to navigate its objects and attributes.

 

Bound License Navigation and Creation

The AD RMS system uses both bound and unbound licenses. Bound licenses include only information relevant to the current computer and user for the current task. Unbound licenses are not filtered in this manner. Bound licenses require a secure environment, but unbound licenses do not. The two license types are not interchangeable.

Function Description
DRMCreateBoundLicense Creates a bound license from a locally stored license.
DRMCreateEnablingPrincipal Creates an enabling principal.
DRMGetBoundLicenseAttribute Retrieves a bound license attribute.
DRMGetBoundLicenseAttributeCount Retrieves the number of occurrences of a particular attribute within a given object.
DRMGetBoundLicenseObject Retrieves an object of a specified type in a bound license.
DRMGetBoundLicenseObjectCount Retrieves the number of occurrences of a particular attribute within a given object.

 

License, Certificate, and Advisory List Management

The AD RMS system maintains a certificate store for each user who logs onto the computer. The AD RMS system also maintains a revocation list that describes licenses, secure repositories, or other objects that have had their rights revoked. This list must be periodically refreshed, in the interval specified by each license.

Function Description
DRMAcquireAdvisories Retrieves revocation lists.
DRMAcquireLicense Attempts to acquire an end-user license or client licensor certificate asynchronously.
DRMAddLicense Adds an end-user license to the temporary license store.
DRMConstructCertificateChain Builds a certificate chain from an arbitrary number of certificates.
DRMDeconstructCertificateChain Retrieves a certificate from a certificate chain.
DRMDeleteLicense Deletes a license, client licensor certificate, or revocation list.
DRMEnumerateLicense Enumerates valid licenses, machine certificates or rights account certificates, and revocation lists for the current user.
DRMGetCertificateChainCount Retrieves the number of certificates in a certificate chain.

 

Cryptography

The AD RMS SDK contains the following cryptographic functions. You should not use other cryptographic systems to handle encryption or decryption of content.

Function Description
DRMAttest Signs data.
DRMCreateEnablingBitsDecryptor Creates a DRMDecrypt object for an enabling principal.
DRMCreateEnablingBitsEncryptor Creates a DRMEncrypt object for an enabling principal.
DRMDecrypt Decrypts symmetrically encrypted data.
DRMEncrypt Encrypts data by using a content key.
DRMVerify Verifies data signed by using DRMAttest.

 

Miscellaneous Functions and Topics

Function Description
DRMDecode Decodes a string that is encoded with a common algorithm, such as base64.
DRMEncode Encodes data by using a public encoding method, such as base64.
DRMGetInfo Retrieves information about an object from its handle.
DRMGetTime Retrieves the time from a secure timer.
AD RMS Function Error Codes Discusses common error codes returned by AD RMS functions.
AD RMS Handles and Sessions Discusses handles to AD RMS objects.

 

AD RMS SDK Reference