IpcEncrypt function
Encrypts plaintext data. For important information about using this function, see Remarks.
Syntax
HRESULT WINAPI IpcEncrypt(
_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]
-
A handle to a key object from IpcGetKey or IpcSerializeLicense.
-
dwBlockNumber
-
The block number (calculated as block number == offset/block size). For information about usage, see Remarks.
-
fFinal
-
Specifies whether this is the last section in a series being encrypted. TRUE for the last or only block; FALSE if there are more blocks to be encrypted.
-
pbInput [in]
-
A pointer to the plaintext to encrypt.
-
cbInput
-
The byte count of the plaintext to encrypt. The length of the plaintext must be a multiple of the block size unless fFinal is FALSE.
-
pbOutput [out]
-
A pointer to the output buffer. On output, this buffer receives the ciphertext.
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 ciphertext.
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 encryption approach
When encrypting data, memory must be allocated by the caller to store the encrypted data. To reduce runtime memory usage, you may choose to encrypt a large amount of contiguous data by breaking it up into smaller blocks first, rather than encrypting 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 encrypt 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 encrypt 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 IpcEncrypt, 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 the next block of data to encrypt, and pbOutput to the proper location to receive the next block of data resulting from that encryption. Set fFinal to TRUE only if you are passing in the last block of data to be encrypted.
Note
Automatic padding is not supported. All segments of data must be a multiple of the platform's block size, as determined by IpcGetKeyProperty.
Padding
In the default case, when fFinal is set to TRUE, the input data does not need to be a multiple of the platform's block size. IpcEncrypt may generate encrypted data that is larger in size than the original data. To ensure correct behavior, you must first query the required size of the encrypted data by calling IpcEncrypt with pbOutput set to NULL. It is not recommended to pad the input data to a multiple of the platform's block size in your application because the platform's block size may be significantly larger than the padding data actually required.
If your application encrypts data that can be consumed by using the MSDRM library, you may choose to set the IPC_LI_DEPRECATED_ENCRYPTION_ALGORITHMS property when creating a license. In this case, automatic padding is not supported. All segments of data must be a multiple of the platform's block size, as determined by IpcGetKeyProperty.
Requirements
| Minimum supported client |
Windows Vista with SP2 |
| Minimum supported server |
Windows Server 2008 |
| Header |
|
| Library |
|
| DLL |
|