DRMCreateIssuanceLicense function (msdrm.h)

[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 DRMCreateIssuanceLicense function creates an issuance license from scratch, from a template, or from a signed issuance license.

Syntax

DRMEXPORT HRESULT UDAPICALL DRMCreateIssuanceLicense(
  [in]           SYSTEMTIME   *pstTimeFrom,
  [in]           SYSTEMTIME   *pstTimeUntil,
  [in]           PWSTR        wszReferralInfoName,
  [in]           PWSTR        wszReferralInfoURL,
  [in, optional] DRMPUBHANDLE hOwner,
  [in]           PWSTR        wszIssuanceLicense,
  [in]           DRMHANDLE    hBoundLicense,
  [out]          DRMPUBHANDLE *phIssuanceLicense
);

Parameters

[in] pstTimeFrom

The starting UTC validity time for the license. If this value is NULL, the pstTimeUntil parameter must also be NULL. If both parameters are not NULL, E_DRM_INVALID_TIMEINFO is returned if the range time is logically inconsistent. For example, pstTimeFrom cannot be later than pstTimeUntil.

[in] pstTimeUntil

The ending UTC validity time for the license. If this value is NULL, the pstTimeFrom parameter must also be NULL. If both parameters are not NULL, E_DRM_INVALID_TIMEINFO is returned if the range time is logically inconsistent. For example, pstTimeFrom cannot be later than pstTimeUntil.

[in] wszReferralInfoName

Nonsilent license acquisition is not supported; set this parameter to NULL.

For Rights Management Services (RMS) client 1.0, this parameter is a pointer to a null-terminated Unicode string that contains the display name for the URL in wszReferralInfoURL. This parameter is optional and can be NULL.

[in] wszReferralInfoURL

Nonsilent license acquisition is not supported; set this parameter to NULL.

For RMS client 1.0, this parameter is a pointer to a null-terminated Unicode string that contains the URL where an application should go to request a license for the content nonsilently. This should be an HTML page that hosts the ActiveX control. This parameter is optional and can be NULL.

[in, optional] hOwner

A handle to the user that owns the issuance license. The handle is created by calling the DRMCreateUser function. The owner is identified under the Owner node in the issuance license XrML. This parameter is optional and can be NULL.

Do not confuse the owner of an issuance license with a user who has been granted the OWNER right. Ownership of an issuance license does not automatically grant any rights to use or modify content. Specifying a value for the optional hOwner parameter merely enables an application to identify the content owner or author. The ID is added as metadata to the license. The OWNER right, on the other hand, grants a user the authority to exercise all rights contained in the license. Granting yourself (or anyone else) the OWNER right must be done explicitly by using DRMAddRightWithUser. Zero, one, or more users can be granted the OWNER right, which never expires.

If specified, the issuance license owner is added as metadata beneath the <WORK> node of the license.

<WORK>
  <OBJECT type="contentType">
    <ID type="contentIdType">contentId</ID>
    <NAME>contentName</NAME>
  </OBJECT>
  <METADATA>
    <OWNER>
      <OBJECT>
        <ID type="Windows"/>
        <NAME>david@contoso.com</NAME>
      </OBJECT>
    </OWNER>
  </METADATA>
  ...

If granted, the OWNER right is added as an attribute of the <RIGHT> element in the license XrML.

<WORK>
  ...
  <RIGHTSGROUP name="MainRights">
    <RIGHTSLIST>
      <VIEW>
        ...
      </VIEW>
      <RIGHT name="OWNER">
        <CONDITIONLIST>
          ...
        </CONDITIONLIST>
      </RIGHT>
    </RIGHTSLIST>
  </RIGHTSGROUP>

[in] wszIssuanceLicense

A pointer to a null-terminated Unicode string that contains an issuance license template or a signed issuance license. You can call the DRMGetIssuanceLicenseTemplate function to retrieve a template. If this parameter is NULL, an issuance license is created.

[in] hBoundLicense

A handle to a bound license that contains the VIEWRIGHTSDATA, EDITRIGHTSDATA or OWNER right, which allows an application to reuse rights data or reuse the content key from a previous issuance license. This parameter is optional and can be NULL. For further information about rights, see Understanding XrML Rights.

[out] phIssuanceLicense

A pointer to a DRMPUBHANDLE that receives the handle to the new issuance license.

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 list. For a list of common error codes, see Common HRESULT Values.

Remarks

An issuance license is a list of rights, users, metadata, and other information that specifies how a specific user on a specific computer is able to use the specified content. This issuance license must be signed by using the DRMGetSignedIssuanceLicense function or the AcquireIssuanceLicense SOAP method. The resulting signed issuance license is given to a potential end user who must then request an end-user license by calling the DRMAcquireLicense function. An application may request an end-user license on behalf of another end user by using the AcquirePreLicense SOAP method. It is only the end-user license that allows an application to exercise the rights that have been granted.

This function allows you to create licenses in three different ways.

When an issuance license (signed or unsigned) is passed in, the following data is reused:

• Users (from DRMCreateUser)
• Rights (from DRMCreateRight)
• Application-specific data (from DRMSetApplicationSpecificData)
• Metadata (from DRMSetMetaData)
• Name and description (from DRMSetNameAndDescription)
• Revocation point (from DRMSetRevocationPoint)
• Usage policy (from DRMSetUsagePolicy)

Because nonsilent license acquisition is not supported, wszReferralInfoName and wszReferralInfoURL should be NULL.

For RMS client 1.0, the referral point described by wszReferralInfoName and wszReferralInfoURL is used as a backup URL if a call to the URL specified in the license header fails. This method allows a caller to define a display name and a URL to a site that handles nonsilent license requests for the content.

The hBoundLicense parameter allows an application to be able to reuse data from an existing issuance license. This is done by having the publishing application create a VIEWRIGHTSDATA right and grant it to any application allowed to reuse the issuance license information. However, because this involves binding to a license, which is a task that cannot be done without using a lockbox, this value should be NULL for server applications that do not use a lockbox.

The purpose of a URL cannot be verified by any part of a client or Active Directory Rights Management Services system. It would be possible for a malicious publisher to include a harmful URL address in an issuance license, although the issuance license creator would need a valid licensed Active Directory Rights Management Services system to do so.

One problem that can arise when creating issuance licenses with short validity times is the problem of clock skew. Clock skew is when the publishing computer's clock and the end user's computer clock are not exactly aligned. Clock skew can cause issuance license signing attempts to fail. For more information, see Clock Skew.

Call DRMClosePubHandle to close the issuance license handle created by calling this function.

Requirements

See also

AD RMS Functions

Creating and Using Issuance Licenses