AD RMS Functions
[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
- Issuance License Creation and Property Setting Functions
- Handle Functions
- Unbound License Navigation
- Bound License Navigation and Creation
- License, Certificate, and Advisory List Management
- Cryptography
- Miscellaneous Functions and Topics
- Related topics
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. |
Related topics