IpcDecrypt function
Decrypts encrypted data. For information about using this function with MSDRM encryption, see Remarks.
Syntax
HRESULT WINAPI IpcDecrypt(
_In_ IPC_KEY_HANDLE hKey,
DWORD dwBlockNumber,
BOOL fFinal,
_In_ PBYTE pbInput,
DWORD cbInput,
_Out_ PBYTE pbOutput,
DWORD cbOutput,
_Out_ DWORD *pcbResult
);
Parameters
-
hKey [in]
-
The handle to a key object from IpcGetKey or IpcSerializeLicense.
-
dwBlockNumber
-
The block number (calculated as block number == offset/block size). For more information on usage, see Remarks.
-
fFinal
-
Specifies whether this is the last section in a series being decrypted. TRUE for the last or only block; FALSE if there are more blocks to be decrypted.
-
pbInput [in]
-
A pointer to the cipher text to decrypt.
-
cbInput
-
The byte count of the cipher text to decrypt. The length of the cipher text must be a multiple of the block size unless fFinal is TRUE.
-
pbOutput [out]
-
A pointer to the output buffer. On output, this buffer receives the plaintext.
Set to NULL to query for the size required for the output buffer.
-
cbOutput
-
The size of the output buffer, in bytes.
-
pcbResult [out]
-
A pointer to a ULONG that receives the number of bytes copied to pbOutput. If pbOutput is NULL, pcbResult receives the size, in bytes, required for the plaintext.
Return value
If the function succeeds, the return value is S_OK. If the function fails, it returns an HRESULT value that indicates the error.
For more information, see Error codes for a description of all RMS SDK 2.1 return values.
Remarks
Data decryption approach
When decrypting data, memory must be allocated by the caller to store the decrypted data. To reduce runtime memory usage, you may choose to decrypt a large amount of contiguous data by breaking it up into smaller blocks first, rather than decrypting all the data in a single call.
Note
Breaking your content into multiple segments and performing multiple calls may also be required if the content of your document is not stored contiguously.
To decrypt a block of data in a single call, pass in 0 (zero) for dwBlockNumber, TRUE for fFinal, and set pbInput to the beginning of your data.
To decrypt a large block of contiguous data over the course of several calls, use the IPC_KI_BLOCK_SIZE property from IpcGetKeyProperty to determine the block size used by the platform. Break up your data into segments that are multiples of this size. For each successive call to IpcDecrypt, set dwBlockNumber to the value of (bytes of data encrypted so far / block size as determined by IpcGetKeyProperty). Be sure to set pbInput to the location of next block of data to decrypt, and pbOutput to the proper location to receive the next block of data to receive the result of that decryption. Set fFinal to TRUE only if you are passing in the last block of data to be decrypted.
Padding
In the default case, when fFinal is set to TRUE, the size of the decrypted data may not be a multiple of the platform's block size. IpcDecrypt will determine the size of the original plaintext data and return this value in pcbResult.
If your application decrypts data that was protected by using either the MSDRM library or the RMS SDK 2.1 library in the case when the IPC_LI_DEPRECATED_ENCRYPTION_ALGORITHMS property was set during license creation, then automatic padding is not supported. The final decrypted block will be a multiple of the platform's block size, as determined by IpcGetKeyProperty.
If your application decrypts data that could be encrypted in either mode, you must query which type of encryption was used to decrypt the final block correctly. Use the IPC_LI_DEPRECATED_ENCRYPTION_ALGORITHMS property to do this.
Compatibility with MSDRM
In most cases, it is possible to use RMS SDK 2.1 to decrypt content encrypted by using MSDRM.
It is also possible to create MSDRM applications that will produce information that RMS SDK 2.1 cannot decrypt.
The following prerequisites will help to ensure decryption is possible:
- The license generated by MSDRM's DRMGetSignedIssuanceLicense specified L"AES" as the wszSymKeyType parameter.
- Content was encrypted by MSDRM in multiples of the blocksize, queried using DRMGetInfo.
- Content is decrypted by RMS SDK 2.1 in multiples of the blocksize, queried using IpcGetKeyProperty .
Testing is the only way to know for sure if your MSDRM-encrypted data can be decrypted by using RMS SDK 2.1.
Requirements
| Minimum supported client |
Windows Vista with SP2 |
| Minimum supported server |
Windows Server 2008 |
| Header |
|
| Library |
|
| DLL |
|