DRMDecrypt function (msdrm.h)

Article
10/13/2021

[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 DRMDecrypt function decrypts encrypted content.

Syntax

DRMEXPORT HRESULT UDAPICALL DRMDecrypt(
  [in]      DRMHANDLE hCryptoProvider,
  [in]      UINT      iPosition,
  [in]      UINT      cNumInBytes,
  [in]      BYTE      *pbInData,
  [in, out] UINT      *pcNumOutBytes,
  [out]     BYTE      *pbOutData
);

Parameters

[in] hCryptoProvider

A handle to an AD RMS decrypting object created by DRMCreateEnablingBitsDecryptor.

[in] iPosition

Position in the buffer at which to start decrypting. 0 corresponds to the first block in a buffer, 1 corresponds to the second block, and so on. See the example later in this topic.

[in] cNumInBytes

Number of bytes to decrypt.

[in] pbInData

Pointer to a buffer that contains the bytes to decrypt.

[in, out] pcNumOutBytes

Size, in bytes, of the decrypted data.

[out] pbOutData

Decrypted data.

Return value

If the function succeeds, the function returns S_OK.

If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see Common HRESULT Values.

Remarks

Memory allocation and release of the decrypted content is the responsibility of the calling function. The following code sample, from Decrypting Content, shows how to decrypt content in blocks. This particular example already knows the size of the content to decrypt and allocates memory beforehand. If you must determine the number of bytes to allocate, however, the required buffer size is returned in the pcNumOutBytes parameter after the first call. Allocate memory and call the function again with pbOutData set to point to the new memory.

#include "DecryptingContent.h"

/*===================================================================
File:      Decryption_DecryptContent.cpp

THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE.

Copyright (C) Microsoft.  All rights reserved.
===================================================================*/

/////////////////////////////////////////////////////////////////////
// The DecryptContent function decrypts content. The content to be 
// decrypted was created by the EncryptingContent example shown 
// earlier in this documentation.
//
HRESULT DecryptContent(
          DRMHANDLE      hBoundLic,
          UINT           uiEncrypted,
          BYTE*          pbEncrypted,
          BYTE**         ppbDecrypted)
{
  HRESULT hr = S_OK;                  // HRESULT return code
  UINT uiBlock = 0;                   // Decryption block size (16)
  UINT uiBytes = 0;                   // Size of uiBlock variable (4)
  UINT uiDecrypted = 0;               // Number of decrypted bytes
  UINT uiOffset = 0;                  // Decryption buffer offset
  DRMHANDLE hEBDecryptor = NULL;      // Decrypting object handle
  DRMENCODINGTYPE eType;

  wprintf(L"\r\nEntering DecryptContent.\r\n");

  // Validate the input parameters.
  if ( NULL==hBoundLic ||
       NULL==pbEncrypted ||
       NULL==ppbDecrypted)
       return E_INVALIDARG;

  // Create a decrypting object.
  hr = DRMCreateEnablingBitsDecryptor( 
          hBoundLic,                // Bound license handle
          L"EDIT",                  // Requested right
          NULL,                     // Reserved
          NULL,                     // Reserved
          &hEBDecryptor);           // Decrypting object pointer
  if (FAILED(hr)) goto e_Exit;
  wprintf(L"DRMCreateEnablingBitsDecryptor: hEBDecryptor = %i\r\n",
          hEBDecryptor);

  // Retrieve the size, in bytes, of the memory block that must 
  // be passed to DRMDecrypt.
  uiBytes= sizeof(uiBlock);
  hr = DRMGetInfo(
          hEBDecryptor,               // Decrypting object handle
          g_wszQUERY_BLOCKSIZE,       // Attribute to query for
          &eType,                     // Type of encoding to apply
          &uiBytes,                   // Size of uiBlock variable
          (BYTE*)&uiBlock);           // Size of memory block
  if(FAILED(hr)) goto e_Exit;
  wprintf(L"DRMGetInfo: uiBlock = %u\r\n", uiBlock);

  // Allocate memory for the decrypted content.
  // Note: This example uses a buffer of known size to store the
  //       decrypted content.  Typically, however, the buffer to 
  //       store the content should be allocated based on the size
  //       returned by the first call to DRMDecrypt.
  *ppbDecrypted = new BYTE[uiEncrypted];
  if (NULL == *ppbDecrypted)
  {
    hr = E_OUTOFMEMORY;
    goto e_Exit;
  }

  // Decrypt the content.
  for ( int j = 0; (UINT)j * uiBlock < uiEncrypted; j++ )
  {
    hr = DRMDecrypt( 
          hEBDecryptor,               // Decrypting object handle
          j * uiBlock,                // Position in the buffer
          uiBlock,                    // Number of bytes to decrypt
          pbEncrypted + (j*uiBlock),  // Bytes to decrypt
          &uiDecrypted,               // Number of decrypted bytes
          NULL);                      // Set to NULL on first call
    if(FAILED(hr)) goto e_Exit;

    hr = DRMDecrypt( 
          hEBDecryptor,               // Decrypting object handle
          j * uiBlock,                // Position in the buffer 
          uiBlock,                    // Number of bytes to decrypt
          pbEncrypted + (j*uiBlock),  // Bytes to decrypt
          &uiDecrypted,               // Number of decrypted bytes
          *ppbDecrypted + uiOffset);  // Decrypted data
    if(FAILED(hr)) goto e_Exit;

    uiOffset += uiDecrypted;          // Increment the buffer offset
  }

e_Exit:

  if (NULL != hEBDecryptor)
  {
    hr = DRMCloseHandle(hEBDecryptor);
    hEBDecryptor = NULL;
  }
  
  wprintf(L"Leaving DecryptContent: hr = %x\r\n", hr);
  return hr;
}

Requirements

Requirement	Value
Target Platform	Windows
Header	msdrm.h
Library	Msdrm.lib
DLL	Msdrm.dll