Share via

CryptProtectData (Windows Embedded CE 6.0)

  • Article

1/6/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

See Also

Reference

Cryptography Functions
CryptUnprotectData
BLOB (Cryptography)

Concepts

Protected Store API

Other Resources