Expand Minimize

DRMGetSignedIssuanceLicenseEx function

[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.0, which leverages functionality exposed by the client in Msipc.dll.]

The DRMGetSignedIssuanceLicenseEx function acquires a signed issuance license offline. When you call the function, you can pass in the handle to a client licensor certificate (CLC) and the handle to a rights account certificate (RAC), therefore specifying the CLC and the RAC to use when acquiring the signed issuance license.

Syntax


 WINAPI DRMGetSignedIssuanceLicenseEx(
  _In_  DRMENVHANDLE hEnv,
  _In_  DRMPUBHANDLE hIssuanceLicense,
  _In_  UINT uFlags,
  _In_  BYTE *pbSymKey,
  _In_  UINT cbSymKey,
  _In_  PWSTR wszSymKeyType,
  _In_  VOID *pvReserved,
  _In_  DRMHANDLE hEnablingPrincipal,
  _In_  DRMHANDLE hBoundLicense,
  _In_  DRMCALLBACK pfnCallback,
  _In_  VOID *pvContext
);

Parameters

hEnv [in]

A handle to a secure environment created by using the DRMInitEnvironment function. The handle is required for offline signing. Applications that do not use a lockbox should pass NULL for this parameter.

hIssuanceLicense [in]

A handle to an issuance license to sign, created by using the DRMCreateIssuanceLicense function.

uFlags [in]

Contains various options for acquiring the signed issuance license. This parameter can be one of the following values (although DRM_AUTO_GENERATE_KEY and DRM_OWNER_LICENSE_NOPERSIST can be combined with other flags). If DRM_AUTO_GENERATE_KEY is not specified, you must provide your own content key with a cryptographic system, such as the CryptoAPI functions from the Platform SDK.

ValueMeaning
DRM_SIGN_OFFLINE

Specifies an offline issuance license signing request. When signing offline, the issuance license is signed by using the client licensor certificate (CLC) obtained during a previous call to DRMAcquireLicense. To get this certificate from the store, use DRMEnumerateLicense. Each CLC is tied to the server that issued it; be sure that you are using the correct client licensor certificate for the issuance license you are publishing.

This flag cannot be combined with the DRM_SIGN_ONLINE or DRM_SERVER_ISSUANCELICENSE flags.

DRM_SIGN_CANCEL

Cancels an online signing request. Offline requests are processed immediately and do not need to be canceled.

DRM_AUTO_GENERATE_KEY

Can be used with one of the preceding flags to have the Active Directory Rights Management Services system generate a content key for you. This key is used in encryption functions. Typically, the key type is AES and the cipher mode is ECB. If this flag is not specified, you must provide your own content key with a cryptographic system, such as with the CryptoAPI functions from the Platform SDK.

Note  If you are using the AD RMS client included in Windows 7, or if you install the CBC hotfix, the value AES_CBC4K can be used to specify the AES algorithm with cipher-block chaining (CBC) cipher mode. See the DRMEncrypt code examples for more information.

DRM_OWNER_LICENSE_NOPERSIST

The owner license is stored in memory instead of the permanent store. The owner license can subsequently be retrieved by the DRMGetOwnerLicense function.

DRM_REUSE_KEY

Causes the content key to be reused. The content key is obtained from the signed issuance license associated with the bound license (hBoundLicense) that is passed in to DRMCreateIssuanceLicense. You must ensure that the bound license is bound to either the EDITRIGHTSDATA or OWNER right. This flag is available only in Windows 7.

Note  This flag must be combined with DRM_SIGN_OFFLINE. You can also optionally combine it with DRM_OWNER_LICENSE_NOPERSIST. These are the only allowed values. The parameters pbSymKey and cbSymKey must be set to 0.

Caution  To avoid security implications, reuse the content key only if users or rights are being added. Additionally, it is a best practice to always generate a new content identifier for the publishing license to avoid an older end-user license being used with the new publishing license.

 

pbSymKey [in]

The content key used to encrypt the document. If this value is NULL, the uFlags parameter must specify DRM_AUTO_GENERATE_KEY or DRM_REUSE_KEY. These uFlags values cause pbSymKey to be ignored.

cbSymKey [in]

The size, in bytes, of the content key. Currently, this parameter can only be 16 unless the uFlags parameter specifies DRM_AUTO_GENERATE_KEY or DRM_REUSE_KEY, in which case this parameter can be zero.

wszSymKeyType [in]

The key type. The value AES specifies the Advanced Encryption Standard (AES) algorithm with the electronic code book (ECB) cipher mode. If you are using Windows 7, the value AES_CBC4K can be used to specify the AES algorithm with cipher-block chaining (CBC) cipher mode. See the DRMEncrypt code examples for more information.

pvReserved [in]

Reserved for future use.

hEnablingPrincipal [in]

A handle to an enabling principal in the end-user license that should be bound. Create this handle by using the DRMCreateEnablingPrincipal function by passing in the rights account certificate. This parameter is required.

hBoundLicense [in]

A handle to the bound license corresponding to the client licensor certificate created using DRMCreateBoundLicense. This can be created by binding the wszClientLicensorCertificate to the ISSUE right using the hEnablingPrincipal handle. This parameter is required.

pfnCallback [in]

A pointer to the callback function used to notify the application of an asynchronous request's progress. For the signature of the callback function you must provide, see Callback Prototype.

pvContext [in]

A 32-bit, application-defined value that is sent in the pvContext parameter of the callback function. This value can be a pointer to data, a pointer to an event handle, or whatever else the custom callback function is designed to handle. For more information, see Creating a Callback Function.

Return value

If the function succeeds, the function returns S_OK.

If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

Return codeDescription
E_DRM_AUTHENTICATION_FAILED

Possibly an HTTP 401 error (authentication error) returned by an Internet request.

E_DRM_INVALID_CLIENT_LICENSOR_CERTIFICATE

You have passed in the wrong client licensor certificate (possibly for the wrong server or a revoked server). Enumerate the client licensor certificates and try another one.

E_DRM_METADATA_NOT_SET

Metadata must exist in the issuance license before it can be signed. Metadata is automatically included if the issuance license was created from a template or existing license that contained metadata. If you created the issuance license from scratch, you must call DRMSetMetaData before calling DRMGetSignedIssuanceLicense.

E_DRM_NEEDS_MACHINE_ACTIVATION

The application is attempting to activate a user but the computer has not been activated, or the current certificate hierarchy does not match the hierarchy of the computer certificate.

E_DRM_RIGHT_NOT_SET

The issuance license must contain one or more rights before it can be signed.

E_DRM_SERVER_ERROR

Unspecified server error or a server-enforced lockbox or rights account certificate (RAC) public key exclusion.

E_DRM_SERVER_NOT_FOUND

Returned when an attempt to contact a service through the Internet returns HTTP 404 (requested server not found).

E_DRM_SERVICE_GONE

Returned when an attempt to contact a Passport service in a rights account certificate activation request returns HTTP 410 (the service is gone).

E_DRM_SERVICE_MOVED

Returned when an attempt to contact a Passport service in a rights account certificate activation request returns HTTP 303 (the service has moved).

E_DRM_SERVICE_NOT_FOUND

The service cannot be found in the UDDI directory.

E_DRM_ISSUANCELICENSE_LENGTH_LIMIT_EXCEEDED

The client issuance license has exceeded the maximum size.

 

Remarks

To use this function, create an enabling principal from the rights account certificate using DRMCreateEnablingPrincipal. After this, you must parse the client licensor certificate(CLC) to obtain the content ID, in the same manner as you do for the end-user license. Subsequently, call DRMCreateBoundLicense, passing in the hEnablingPrincipal obtained from the call to DRMCreateEnablingPrincipal and the content ID to create an hBoundLicense that corresponds with the CLC. Next, call DRMGetSignedIssuanceLicenseEx, passing in the hEnablingPrincipal obtained from the call to DRMCreateEnablingPrincipal and the hBoundLicense obtained from the call to DRMCreateBoundLicense. Finally, cache the handles obtained from the call to DRMCreateEnablingPrincipal and the call to DRMCreateBoundLicense.

Requirements

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Msdrm.h

Library

Msdrm.lib

DLL

Msdrm.dll

See also

AD RMS Functions
Creating and Using Issuance Licenses
Offline Signing Code Example
Online Signing Code Example

 

 

Show:
© 2014 Microsoft