CryptUnprotectData

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function decrypts and checks the integrity of the data in a BLOB (Cryptography) structure. Usually, only a user with the same logon credentials as the encrypter can decrypt the data. In addition, the encryption and decryption must be done on the same computer.

Syntax

BOOL WINAPI CryptUnprotectData(
  DATA_BLOB* pDataIn, 
  LPWSTR* ppszDataDescr, 
  DATA_BLOB* pOptionalEntropy, 
  PVOID pvReserved, 
  CRYPTPROTECT_PROMPTSTRUCT* pPromptStruct, 
  DWORD dwFlags, 
  DATA_BLOB* pDataOut 
);

Parameters

• pDataIn
  [in] Pointer to a BLOB (Cryptography) structure that holds the encrypted data. The DATA_BLOB structure's cbData member holds the length of the pbData member's byte string that contains the text to be encrypted.

• ppszDataDescr
  [out] Optional. Pointer to a readable string description of the encrypted data.

• pOptionalEntropy
  [in] Optional. Pointer to a BLOB containing a password or other additional entropy used when the data was encrypted. This parameter is optional and can be set to NULL; however, if an optional entropy BLOB was used in the encryption phase, that same BLOB must be used for the decryption phase.

• pvReserved
  [in] Reserved for future use and must be set to NULL.

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

• dwFlags
  [in] Must match the value specified during the encryption process. If the flag is set, the calling process must be privileged. 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 where the function stores the decrypted data. cbData and pbData members of pDataOut should be set to 0.

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Remarks

For information about exceptions, see the Remarks section for the CryptProtectData function.

The CryptProtectData function creates a session key when the data is encrypted. That key is derived again and used to decrypt the data BLOB.

The message authentication code (MAC) hash added to the encrypted data can be used to determine whether the encrypted data was altered in any way. Any tampering results in the return of the ERROR_INVALID_DATA code.

The pbData member of the allocated DATA_BLOB structure and any non-NULL ppszDataDescr parameter must be freed using the LocalFree function.

The encrypted data contained within the blob is self describing and includes the size needed to decrypt the data. The size field of the data blob is used only for a basic bounds check; to check the lower boundary and ensure that the size is the minimum needed. This means that while the size field can be set to be greater than the actual size of the data that was encrypted, only the actual data blob will be decrypted. No error will result if the size field is set to be larger than the actual size of the data blob.

You can store the encryption or master keys used by CryptUnprotectData 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

CryptProtectData
BLOB (Cryptography)

Other Resources

LocalFree