Platform SDK: Cryptography

CPEncrypt

The CPEncrypt function encrypts data. Optionally, the application can specify that a hash of the paintext data is to be generated.

BOOL CPEncrypt(
  HCRYPTPROV hProv,       // in
  HCRYPTKEY hKey,         // in
  HCRYPTHASH hHash,       // in
  BOOL Final,             // in
  DWORD dwFlags,          // in
  BYTE *pbData,           // in, out
  DWORD *pdwDataLen,      // in, out
  DWORD dwBufLen          // in
);

Parameters

hProv

Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext.

hKey

Handle to the key to use for the encryption. This key handle includes a a specification of the encryption algorithm to be used.

hHash

Handle to a hash object. This parameter is used only if a hash of the data is to be computed before time the data is encrypted.

This parameter is zero if no hash is to be done.

Final

Boolean value that specifies whether this is the last section in a series being encrypted. This will be TRUE if this is the last or only block, and FALSE otherwise.

dwFlags

No flags are currently defined.

pbData

Buffer holding the plaintext to be encrypted. Once the encryption has been performed, the ciphertext overwrites the plaintext in the pbdata buffer.

pdwDataLen

Address of a DWORD indicating byte length. Upon function entry, this DWORD specifies the number of bytes of plaintext in the pbData buffer. If a block cipher is used and dwFlags is FALSE, this must be a multiple of the cipher block length so that the CPEncrypt function need not buffer any data internally.

Upon exit, this DWORD indicates length in bytes of ciphertext in the pbData buffer.

When a block cipher is used, the size of the ciphertext generated is sometimes larger than that of the plaintext. However, it must never be greater than dwBufLen.

dwBufLen

Size of the pbData buffer in bytes.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError.

Error	Description
NTE_BAD_ALGID	The hKey session key specifies an algorithm that this CSP does not support.
NTE_BAD_DATA	The data to be encrypted is invalid. For example, when a block cipher is used and the Final flag FALSE, the value specified by pdwDataLen must be a multiple of the block size.
NTE_BAD_FLAGS	The dwFlags parameter is non-zero.
NTE_BAD_HASH	The hHash parameter contains an invalid handle.
NTE_BAD_HASH_STATE	An attempt was made to add data to a hash object that is already marked "finished."
NTE_BAD_KEY	The hKey parameter does not contain a valid handle to a key.
NTE_BAD_LEN	The size of the output buffer is too small to hold the generated ciphertext.
NTE_BAD_UID	The CSP context that was specified when the key was created cannot now be found.
NTE_DOUBLE_ENCRYPT	The application attempted to encrypt the same data twice.
NTE_FAIL	The function failed in some unexpected way.
NTE_NO_MEMORY	The CSP ran out of memory during the operation.

Remarks

In Windows 2000, the Microsoft Enhanced RSA Provider supports direct encryption with RSA public keys and decryption with RSA private keys. The encryption is done with PKCS #1 Type 2 padding, and on decryption this padding is verified. The length of plaintext data that can be encrypted with a call to CPEncrypt with an RSA key is the length of the key modulus minus 11 bytes. The 11 bytes is the chosen minimum for PKCS #1 padding. The ciphertext is returned in little endian format.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 OSR2 or later (or Windows 95 with Internet Explorer 3.02 or later).
  Header: Declared in Wincrypt.h.

CPEncrypt

Parameters

Return Values

Remarks

Requirements

See Also