Creating an AD RMS Decrypting Object

Article
03/13/2008

You can use an AD RMS decrypting object to decrypt content so that it can be displayed, edited, and so on. A decrypting object is linked to a single right in a bound license, and it receives a content key associated with that right.

Because decrypted content is unprotected, it is recommended that your application disable menu items and shortcut keys that you do not want end users to choose.

A bound license can grant multiple rights to a user, but it is possible for each right to be associated with a separate key. For example, the key required to decrypt content for editing can be different than the key required to decrypt content for printing. Therefore, if you expect that a single file can be associated with multiple keys, it is recommended that you create a different decrypting object for each right.

The following example shows how to create a decrypting object for the EDIT right. The example binds to a license before creating a decrypting object. For more information, see Binding to the License.


//--------------------------------------------------------------------
// The CreateDecryptObject function shows how to bind a 
// license to the EDIT right and create an AD RMS decrypting object.
//
// Parameters:
//   hEnv -                        Secure environment handle.
//   hDefaultLibrary -             Library handle.
//   hLicenseStorage -             License storage session handle.
//   wszEULCertificateData -       End-user license.
//   wszGroupIDCertificateData -   Rights account certificate. 
//
HRESULT CreateDecryptObject(
                             DRMHANDLE hEnv, 
                             DRMHANDLE hDefaultLibrary, 
                             DRMHSESSION  hLicenseStorage,
                             PWSTR     wszGroupIDCertificateData, 
                             PWSTR     wszEULCertificateData )
{

//--------------------------------------------------------------------
// Declare variables.
//
// hEnablingPrincipal - Handle to enabling principal needed to bind.
// hBoundLicense -      Handle to a bound license.
// hEBDecryptor -       Handle to a decrypt object.
// wszRevocationList -  String that contains the license.
// idNULL -             DRMID structure.
// idStandardEP -       DRMID structure.
// idContent -          DRMID structure.
// oParams -            DRMBOUNDLICENSEPARAMS structure.
//
HRESULT      hr                 = S_OK;
DRMHANDLE    hEnablingPrincipal = NULL;
DRMHANDLE    hBoundLicense      = NULL;
DRMHANDLE    hEBDecryptor       = NULL;
PWSTR        wszRevocationList  = NULL;

DRMID        idNULL;
DRMID        idStandardEP;
DRMID        idContent;

DRMBOUNDLICENSEPARAMS oParams;

idNULL.uVersion  = 0;
idNULL.wszIDType = NULL;
idNULL.wszID     = NULL;

idStandardEP.uVersion  = 0;
idStandardEP.wszIDType = L"ASCII Tag";
idStandardEP.wszID     = L"UDStdPlg Enabling Principal";

idContent.uVersion  = 0;
idContent.wszIDType = L"ContentIdType";
idContent.wszID     = L"ContentId";

if( NULL == hEnv || 
    NULL == hDefaultLibrary ||
    NULL == hLicenseStorage ||
    NULL == wszGroupIDCertificateData ||
    NULL == wszEULCertificateData )
{
  hr = E_INVALIDARG;
  goto e_Exit;
}

//--------------------------------------------------------------------
// Create the enabling principal. The handle returned by the
// DRMCreateEnablingPrincipal is set in the DRMBOUNDLICENSEPARAMS 
// structure used to define the license being requested.
//
hr = DRMCreateEnablingPrincipal (
        hEnv,                       // secure environment handle
        hDefaultLibrary,            // library handle
        idStandardEP.wszID,         // enabling principal type
        &idNULL,                    // DRMID structure
        wszGroupIDCertificateData,  // current user certificate
        &hEnablingPrincipal         // enabling principal handle
        );
if(FAILED(hr))
{
  wprintf(L"\nDRMCreateEnablingPrincipal failed. " \
          L"hr = 0x%x\n", hr);
  goto e_Exit;
}

wprintf(L"\nDRMCreateEnablingPrincipal succeeded.\n");

oParams.hEnablingPrincipal                     = hEnablingPrincipal;
oParams.hSecureStore                           = NULL;
oParams.wszRightsRequested                     = L"EDIT";
oParams.wszRightsGroup                         = L"Main-Rights";
oParams.idResource                             = idContent;
oParams.wszDefaultEnablingPrincipalCredentials = NULL;
oParams.cAuthenticatorCount                    = 0;

//--------------------------------------------------------------------
// Bind the license to the EDIT right.
//
hr = DRMCreateBoundLicense ( 
        hEnv,                    // secure environment handle
        &oParams,                // additional license options
        wszEULCertificateData,   // end-user license
        &hBoundLicense,          // handle to bound license
        NULL                     // reserved
        );


if(FAILED(hr))
{
  wprintf(L"\nDRMCreateBoundLicense(EDIT) failed. hr = 0x%x\n", hr);
  goto e_Exit;
}

//--------------------------------------------------------------------
// Create a decrypting object so that content can be decrypted.
//
hr = DRMCreateEnablingBitsDecryptor( 
        hBoundLicense,              // handle to a bound license
        oParams.wszRightsRequested, // the EDIT right
        NULL,                       // must be NULL
        NULL,                       // must be NULL
        &hEBDecryptor               // AD RMS decrypting object
        );

if(FAILED(hr))
{
  wprintf(L"\nDRMCreateEnablingBitsDecryptor(VIEW) failed. " \
          L"hr = 0x%x\n", hr);
  goto e_Exit;
}

//--------------------------------------------------------------------
// Perform cleanup.
//
e_Exit:

    if( NULL != wszRevocationList )
    {
        HeapFree(GetProcessHeap(), 0, wszRevocationList);
    }

    if(NULL != hEnablingPrincipal)
    {
        DRMCloseHandle( hEnablingPrincipal );
    }

    if(NULL != hBoundLicense)
    {
        DRMCloseHandle( hBoundLicense );
    }

 return hr;

}

Share via

Creating an AD RMS Decrypting Object

See Also

Additional resources