Creating an Application That Uses a Server Lockbox

By using the following example, you can build an AD RMS-enabled application that uses a server lockbox. If you are unsure which type of lockbox to use in your application, see Determining Whether to Use a Lockbox.

Before using this example, ensure that the following tasks are complete:

• The client is running Rights Management Services client 1.0 SP1.
• The hierarchy is set to Pre-production. This is controllable through the client's hierarchy registry setting. For information about specifying the Pre-production hierarchy, see Client Hierarchy Registry Value.
• The intended RMS server is running Rights Management Services 1.0 SP1.
• A discretionary access control list (DACL) that specifies the proper access has been applied to the server certification Web service file. The name of the server certification Web service file is ServerCertification.asmx.
• If the application will be run under the network service account, the application must use the WinHTTP protocol. This protocol is selected by calling the DRMSetGlobalOptions function with the DRMGLOBALOPTIONS_USE_WINHTTP option. The DRMSetGlobalOptions function must be called prior to calling any other AD RMS functions.

The following C++ example shows how to enable an application to use a server lockbox.

It follows these steps:

1. The application specifies that the server lockbox is to be used by calling the DRMSetGlobalOptions function with DRMGLOBALOPTIONS_USE_SERVERSECURITYPROCESSOR specified.

   (Optional). The application specifies that the WinHTTP protocol is to be used by calling the DRMSetGlobalOptions function with DRMGLOBALOPTIONS_USE_WINHTTP specified. You can omit this step if you want to use the WinInet protocol.

   For an example of this step, see the example C++ function SetGlobalOptions.

2. The application determines the user identity to use for creating the client session. For an example of determining the user identity, see the example C++ function GetGroupIDNames.

HRESULT SetGlobalOptions()
{
    HRESULT hr = S_OK;
    BOOL fTrue = TRUE;
 
    hr = DRMSetGlobalOptions(
            DRMGLOBALOPTIONS_USE_SERVERSECURITYPROCESSOR,
            (void*)&fTrue,
            sizeof(BOOL));
    if (FAILED(hr))
        goto e_Exit;
 
    hr = DRMSetGlobalOptions(   
            DRMGLOBALOPTIONS_USE_WINHTTP,
            (void*)&fTrue,
            sizeof(BOOL));
 
    if (FAILED(hr))
        goto e_Exit;
 
e_Exit:
    return hr;
}
 
HRESULT GetGroupIDNames(PWSTR** ppwszGroupId,UINT* pcGroupId)
{
    HRESULT hr = S_OK;
 
    DRMHSESSION hClient = NULL;
 
    UINT cGroupId = 0;
 
    UINT uIndex = 0;
 
    BOOL fSharedFlag = FALSE;
    UINT uCertLen = 0;
 
    PWSTR* pwszGroupId = NULL;
 
    hr = DRMCreateClientSession(
                  &OnStatus1,  // Application-defined callback
                  DRMCALLBACKVERSION,
                  DRM_DEFAULTGROUPIDTYPE_WINDOWSAUTH,
                  NULL,
                  &hClient);
 
    if (FAILED(hr))
        goto e_Exit;
 
    while(hr == S_OK)
    {
        hr = DRMEnumerateLicense(
                        hClient,
                        DRM_EL_GROUPIDENTITY_NAME,
                        cGroupId,
                        &fSharedFlag,
                        &uCertLen,
                        NULL);
 
        if (hr == E_DRM_NO_MORE_DATA)
        {
            hr = S_OK;
            break;
        }
 
        cGroupId++;
    }
    
    if (cGroupId == 0)
    {
        hr = E_DRM_NEEDS_GROUPIDENTITY_ACTIVATION;
        goto e_Exit;
    }
 
    pwszGroupId = new PWSTR[cGroupId];
    if (pwszGroupId == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto e_Exit;
    }
 
    while(hr == S_OK && uIndex < cGroupId)
    {
        hr = DRMEnumerateLicense(
                        hClient,
                        DRM_EL_GROUPIDENTITY_NAME,
                        uIndex,
                        &fSharedFlag,
                        &uCertLen,
                        NULL);
 
        if (hr == E_DRM_NO_MORE_DATA)
        {
            hr = S_OK;
            break;
        }
 
        pwszGroupId[uIndex] = new WCHAR[uCertLen];
        if (pwszGroupId[uIndex] == NULL)
        {
            hr = E_OUTOFMEMORY;
            goto e_Exit;
        }
 
        hr = DRMEnumerateLicense(
                        hClient,
                        DRM_EL_GROUPIDENTITY_NAME,
                        uIndex,
                        &fSharedFlag,
                        &uCertLen,
                        pwszGroupId[uIndex]);
 
        uIndex++;
    }
 
    *ppwszGroupId = pwszGroupId;
    *pcGroupId    = cGroupId;
 
    pwszGroupId = NULL;
 
e_Exit:
    DRMCloseSession(hClient);
 
    if (pwszGroupId)
    {
        for(UINT i=0;i<cGroupId;i++)
            delete[] pwszGroupId[i];
 
        delete[] pwszGroupId;
    }
 
    return hr;
}

Send comments about this topic to Microsoft

Build date: 3/13/2008