CryptProtectData
A version of this page is also available for
4/8/2010
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.
Note
A normal application can call the CryptProtectData function. The call will fail only if CRYPTPROTECT_SYSTEM is specified for the dwFlags parameter.
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 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 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.
Note
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.
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
| Header | wincrypt.h |
| Library | coredll.lib |
| Windows Embedded CE | Windows CE .NET 4.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |
See Also
Reference
CryptUnprotectData
BLOB (Cryptography)