CryptProtectData

[This is preliminary documentation and subject to change.]

CryptProtectData performs encryption on the data in a DATA_BLOB. Typically, only a user with the same login credential as the encrypter can decrypt the data. In addition, the encryption and decryption normally must be done on the same computer. See "Remarks" for information about exceptions.

BOOL WINAPI CryptProtectData(
  DATA_BLOB *DataIn,                        // in
  LPCWSTR szDataDescr,                      // in
  DATA_BLOB *pOptionalEntropy,              // in optional
  PVOID *pvReserved,                        // reserved
  CRYPTPROTECT_PROMPTSTRUCT *pPromptStruct, // in optional
  DWORD dwFlags                             // in
  DATA_BLOB *pDataOut;                      // out
);

Parameters

DataIn

Pointer to a DATA_BLOB that holds the cleartext to be encrypted.

szDataDescr

String with a readable description of the data to be encrypted. This description is included with the encrypted data. This parameter may be set to NULL.

pOptionalEntropy

Any additional entropy to be added to the encryption process. This might be a password set by the user. Any pOptionalEntropy used in the encryption phase must also be used in the decryption phase. This parameter may be set to NULL for no additional entropy.

pvReserved

Currently not used. Must be set to NULL.

pPromptStruct

Pointer to a data structure that provides information about where and when prompts are to be displayed and what the content of those prompts will be. The parameter is optional and may be set to NULL in both the encryption and decryption phases.

dwFlags

The following dwFlags are defined:

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 was called can use CryptUnprotectData to decrypt the data.
CRYPTPROTECT_UI_FORBIDDEN: This flag is used for remote situations where the user interface (UI) is not an option. When this flag is set and UI is specified for either the protect or unprotect operation, the operation fails and GetLastError returns ERROR_PASSWORD_RESTRICTION.

pDataOut

Pointer to a DATA_BLOB where the function stores the encrypted data. .

Return Values

The function returns TRUE if the function succeeded, FALSE if it failed. GetLastError returns the code for the cause of any failure. The pbData of the DATA_BLOB allocated must be freed using LocalFree.

Remarks

Typically, only a user with login credentials matching those of the encrypter can decrypt the data. In addition, decryption normally can only be done on the computer where the data was encrypted. However, a user with a roaming profile may decrypt the data from another computer on the network.

If the CRYPTPROTECT_LOCAL_MACHINE dwFlag is set when the data is encrypted, any user on the machine where the encryption was done can decrypt the data.

The function creates a session key to perform the encryption. The session key is re-derived when the data is to be decrypted.

The function also adds a MAC (keyed integrity check) to the encrypted data to guard against data tampering.

France currently forbids this kind of encryption by law. In France, the Crypto API encryption call fails. The data protection function will ensure the integrity of the data but will not encrypt it.

Example

// Encrypt data from DATA_BLOB Datain to DATA_BLOB DataOut.
// Then Decrypt to DATA_BLOB DataVerify.
// Declare and initialize variables
DATA_BLOB DataIn, DataOut, DataVerify;
BYTE *pbDataInput =(BYTE *)"Hello world of data protection.";
DWORD cbDataInput = strlen(pbDataInput)+1;
DataIn.pbData = pbDataInput;    
DataIn.cbData = cbDataInput;
printf("the data to be encrypted is--- %s\n",pbDataInput);

CRYPTPROTECT_PROMPTSTRUCT PromptStruct;
ZeroMemory(&PromptStruct, sizeof(PromptStruct));
PromptStruct.cbSize = sizeof(PromptStruct);
PromptStruct.szPrompt = L"This is a user prompt.";
PromptStruct.dwPromptFlags = CRYPTPROTECT_PROMPT_ON_PROTECT;

printf("Begin protect phase\n");
if(!CryptProtectData(
        &DataIn,
        L"This is the description string.", // A description sting. 
        NULL,                // Optional entropy not used
        NULL,                // Reserved
        &PromptStruct,       // Pass a promptstruct
        0,
        &DataOut)){
    // The function failed. Report the error.   
    printf("Encryption error! errorcode=%lu \n",GetLastError());
    return ;
    }
printf("Begin Unprotect phase\n");
LPWSTR pDescrOut = (LPWSTR)0xbaadf00d ; // NULL;
if (!CryptUnprotectData(
        &DataOut,
        &pDescrOut,
        NULL,                 // Optional Entropy,
        NULL,                 // Reserved
        &PromptStruct,        // optional promptstruct
        0,
        &DataVerify)){
    //  The function faild. Report the error.    
    printf("Decryption error! errorcode=%lu\n", GetLastError());
    return;
    }
printf("The decrypted data is--%s\n", DataVerify.pbData);
printf("The description of the data was -- %s\n",pDescrOut);
LocalFree(pDescrOut);
// At this point, memcmp() could be used to compare DataIn.pbData and 
// DataVerify.pbDate for equality. If the two functions worked
// correctly, the two byte strings should be identical. 
LocalFree(DataOut.pbData);
LocalFree(DataVerify.pbData);

QuickInfo