Share via

CryptProtectData

  • Article

This function performs encryption on the data in a DATA_BLOB 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.

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

BOOL WINAPI CryptProtectData(DATA_BLOB* pDataIn,LPCWSTRszDataDescr,DATA_BLOB* pOptionalEntropy,PVOIDpvReserved,CRYPTPROTECT_PROMPTSTRUCT* pPromptStruct,DWORDdwFlags,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 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] 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 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 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.

Return Values

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.

Warning   If the logon credentials are lost or forgotten, the data is usually unrecoverable. However, if the dwFlags parameter in the CryptProtectData function is set to CRYPTPROTECT_LOCAL_MACHINE with or without additional entropy specified in the pOptionalEntropy parameter, any user on the same computer where the data was encrypted can recover the data.

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.

Requirements

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

See Also

CryptUnprotectData | DATA_BLOB

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.