CryptProtectData (Compact 2013)

3/28/2014

This function performs encryption on the data in a BLOB (Cryptography) structure. Typically, only a user with the same logon credentials as the encrypter can decrypt the data. In addition, the encryption and decryption usually must be done on the same computer. For information about exceptions, see the Remarks section.

Syntax

BOOL WINAPI CryptProtectData(
  DATA_BLOB* pDataIn, 
  LPCWSTR szDataDescr, 
  DATA_BLOB* pOptionalEntropy, 
  PVOID pvReserved, 
  CRYPTPROTECT_PROMPTSTRUCT* pPromptStruct, 
  DWORD dwFlags, 
  DATA_BLOB* pDataOut 
);

Parameters

• pDataIn
  [in] Pointer to a DATA_BLOB structure containing the plaintext to be encrypted.

• szDataDescr
  [in] String with a readable description of the data to be encrypted. This description string is included with the encrypted data.

• pOptionalEntropy
  [in] Pointer to a binary large object (BLOB) containing a password or other additional entropy used to encrypt the data. The BLOB used in the encryption phase must also be used in the decryption phase. This parameter can be set to NULL for no additional entropy.

• pvReserved
  [in] Reserved; must be set to NULL.

• pPromptStruct
  [in] Must be set to NULL because the CRYPTPROTECT_PROMPTSTRUCT structure is not used.

• dwFlags
  [in] Bitmask of flags. The following table shows the flag values that are defined.

  Value	Description
  CRYPTPROTECT_LOCAL_MACHINE	When this flag is set, it associates the data encrypted with the current computer instead of with an individual user. Any user on the computer on which CryptProtectData is called can use the CryptUnprotectData function to decrypt the data.
  CRYPTPROTECT_NO_RECOVERY	This flag is not supported and is ignored when specified. No recovery mechanism is supported.
  CRYPTPROTECT_SYSTEM	When this flag is set, only a privileged process can encrypt the data.
  CRYPTPROTECT_UI_FORBIDDEN	This flag is used for remote situations where presenting a user interface (UI) is not an option. When this flag is set and the UI is specified for the protect or unprotect operation, the operation fails and the GetLastError function returns the ERROR_PASSWORD_RESTRICTION code.

• pDataOut
  [out] Pointer to a DATA_BLOB structure that receives the encrypted data. If the pbData member of DATA_BLOB is set to NULL, the function allocates memory for the encrypted data. If the pbData is not equal to NULL, the function uses the buffer specified in cbData of the DATA_BLOB. When you want the function to use the specified buffer, you must verify that the structure is initialized. Passing uninitialized DATA_BLOB may cause unexpected results. When you have finished using the DATA_BLOB structure, free its pbData member by calling the LocalFree function.

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. For extended error information, call the GetLastError function.

Remarks

Only a user with logon credentials matching those of the encrypter can decrypt the data. In addition, decryption usually can only be done on the computer where the data was encrypted.

If an application running as a driver or service calls CryptProtectData early in the boot process, before a user has been established, the function will implicitly add the CRYPTPROTECT_LOCAL_MACHINE flag.

The function creates a session key to perform the encryption. The session key is derived again when the data is to be decrypted.

The function also adds a message authentication code (MAC), which is a keyed integrity check, to the encrypted data to guard against data tampering.

Under some circumstances, Microsoft cryptographic service providers (CSPs) may not allow encryption when used in France, in which case this function fails with the error code NTE_PERM.

You can store the encryption or master keys used by CryptProtectData in a file in the Windows folder or in the system registry so that certain persistent registry implementations will retain the encryption keys after losing and regaining power.

Requirements

See Also

Reference

Cryptography Functions
CryptUnprotectData
BLOB (Cryptography)