Share via


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
Ipcprot.h (include Msipc.h)
Library
Msipc.lib
DLL
Msipc.dll

See also

IpcEncrypt

IpcGetKey

IpcGetKeyProperty

IpcSerializeLicense

Error codes