CryptUnprotectData

[This is preliminary documentation and subject to change.]

CryptUnprotectData performs a decryption and integrity check of the data in a DATA_BLOB. Normally, only a user with the same login credential as the encrypter can decrypt the data. In addition, the encryption and decryption must be done on the same computer. See "Remarks" in CryptProtectData for information about exceptions.

BOOL WINAPI CryptUnprotectData(
  DATA_BLOB *DataIn,                         // in
  LPWSTR *ppszDataDescr,                     // out optional
  DATA_BLOB *pOptionalEntropy,               // in optional
  PVOID *pvReserved,                         // reserved
  CRYPTPROTECT_PROMPTSTRUCT *pPromptStruct,  // in optional
  DWORD dwFlags                              // in
  DATA_BLOB *pDataOut;                       // out
);

Parameters

DataIn

Pointer to a DATA_BLOB that holds the encrypted data. The DATA_BLOB's cbData member holds the length of the pbData byte string that contains the text to be encrypted.

ppszDataDescr

Pointer to an address where a readable description of the encrypted data included with the encrypted data will be placed. This parameter is optional and may be set to NULL.

pOptionalEntropy

Pointer to a string that holds a password or other additional entropy used when the data was encrypted. This parameter is optional and may be set to NULL; however, if optional entropy was used in the encryption phase, that same entropy must be used for decryption phase.

pvReserved

Currently not used. Must be set to NULL.

pPromptStruct

Pointer to a data structure that provides information about where and when prompts are displayed and what the content of those prompts will be. This parameter is optional and may be set to NULL.

dwFlags

CRYPTPROTECT_UI_FORBIDDEN is used for remote situations where the user interface (UI) is not an option. When this flag is set and UI is specified for either the protect or unprotect operation, the operation fails and GetLastError returns ERROR_PASSWORD_RESTRICTION.

pDataOut

Pointer to a DATA_BLOB where the function stores the decrypted data.

Return Values

The function returns TRUE if the function succeeded, FALSE if it failed. GetLastError returns the code for the cause of any failure. The pbData of the DATA_BLOB allocated and a non NULL ppszDataDescr must be freed using LocalFree.

Remarks

The CryptProtectData function creates a session key when the data is encrypted. That key is re-derived and used to decrypt the data blob.

The 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 a ERROR_INVALID_DATA return.

Example

See example using CryptProtectData.

QuickInfo