See Also
 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
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 CryptProtectDatafunction. The call will fail only if CRYPTPROTECT_SYSTEM is specified for the dwFlagsparameter. |
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_BLOBstructure 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_PROMPTSTRUCTstructure 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 CryptProtectDatais called can use the CryptUnprotectDatafunction 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 GetLastErrorfunction returns the ERROR_PASSWORD_RESTRICTION code.
- pDataOut
-
[out] Pointer to a DATA_BLOBstructure that receives the encrypted data. If the pbDatamember of DATA_BLOBis 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 cbDataof the DATA_BLOB.When you want the function to use the specified buffer, you must verify that the structure is initialized. Passing uninitialized DATA_BLOBmay cause unexpected results. When you have finished using the DATA_BLOBstructure, free its pbDatamember by calling the LocalFreefunction.
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 GetLastErrorfunction.
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 CryptProtectDataearly 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 dwFlagsparameter in the CryptProtectDatafunction is set to CRYPTPROTECT_LOCAL_MACHINE with or without additional entropy specified in the pOptionalEntropyparameter, 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 CryptProtectDatain 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 |