CryptUnprotectData

  • Article

This function decrypts and checks the integrity of the data in a DATA_BLOB 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.

Note   An untrusted application can call the CryptUnprotectData function. The call will fail only if CRYPTPROTECT_SYSTEM is specified for the dwFlags parameter.

BOOL WINAPI CryptUnprotectData(DATA_BLOB* pDataIn,LPWSTR* ppszDataDescr,DATA_BLOB* pOptionalEntropy,PVOIDpvReserved,CRYPTPROTECT_PROMPTSTRUCT* pPromptStruct,DWORDdwFlags,DATA_BLOB* pDataOut);

Parameters

  • pDataIn
    [in] Pointer to a DATA_BLOB 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 trusted. 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 trusted 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.

Return Values

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.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Wincrypt.h.
Link Library: Coredll.lib.

See Also

CryptProtectData | LocalFree | DATA_BLOB

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.