CryptProtectData function

The CryptProtectData function performs encryption on the data in a DATA_BLOB structure. Typically, only a user with the same logon credential as the user who encrypted the data can decrypt the data. In addition, the encryption and decryption usually must be done on the same computer.

Syntax

1
2
3
4
5
6
7
8
9

DPAPI_IMP BOOL CryptProtectData(
  DATA_BLOB                 *pDataIn,
  LPCWSTR                   szDataDescr,
  DATA_BLOB                 *pOptionalEntropy,
  PVOID                     pvReserved,
  CRYPTPROTECT_PROMPTSTRUCT *pPromptStruct,
  DWORD                     dwFlags,
  DATA_BLOB                 *pDataOut
);

Parameters

1

pDataIn

A pointer to a DATA_BLOB structure that contains the plain text to be encrypted.

1

szDataDescr

A string with a readable description of the data to be encrypted. This description string is included with the encrypted data. This parameter is optional and can be set to NULL.

1

pOptionalEntropy

A pointer to a DATA_BLOB structure that contains a password or other additional entropy used to encrypt the data. The DATA_BLOB structure used in the encryption phase must also be used in the decryption phase. This parameter can be set to NULL for no additional entropy.

1

pvReserved

Reserved for future use and must be set to NULL.

1

pPromptStruct

A pointer to a CRYPTPROTECT_PROMPTSTRUCT structure that provides information about where and when prompts are to be displayed and what the content of those prompts should be. This parameter can be set to NULL in both the encryption and decryption phases.

1

dwFlags

This parameter can be one of the following flags.

1

pDataOut

A pointer to a DATA_BLOB structure that receives the encrypted data. 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 function returns TRUE.

If the function fails, it returns FALSE.

CryptUnprotectData function

The CryptUnprotectData function decrypts and does an integrity check of the data in a DATA_BLOB structure. Usually, the only user who can decrypt the data is a user with the same logon credentials as the user who encrypted the data. In addition, the encryption and decryption must be done on the same computer.

Syntax

1
2
3
4
5
6
7
8
9

DPAPI_IMP BOOL CryptUnprotectData(
  DATA_BLOB                 *pDataIn,
  LPWSTR                    *ppszDataDescr,
  DATA_BLOB                 *pOptionalEntropy,
  PVOID                     pvReserved,
  CRYPTPROTECT_PROMPTSTRUCT *pPromptStruct,
  DWORD                     dwFlags,
  DATA_BLOB                 *pDataOut
);

Parameters

1

pDataIn

A pointer to a DATA_BLOB structure that holds the encrypted data. The DATA_BLOB structure’s cbData member holds the length of the pbData member’s byte string that contains the text to be encrypted.

1

ppszDataDescr

A pointer to a string-readable description of the encrypted data included with the encrypted data. This parameter can be set to NULL. When you have finished using ppszDataDescr, free it by calling the LocalFree function.

1

pOptionalEntropy

A pointer to a DATA_BLOB structure that contains a password or other additional entropy used when the data was encrypted. This parameter can be set to NULL; however, if an optional entropy DATA_BLOB structure was used in the encryption phase, that same DATA_BLOB structure must be used for the decryption phase.

1

pvReserved

This parameter is reserved for future use and must be set to NULL.

1

pPromptStruct

A pointer to a CRYPTPROTECT_PROMPTSTRUCT structure that provides information about where and when prompts are to be displayed and what the content of those prompts should be. This parameter can be set to NULL.

1

dwFlags

A DWORD value that specifies options for this function. This parameter can be zero, in which case no option is set, or the following flag.

1

pDataOut

A pointer to a DATA_BLOB structure where the function stores the decrypted data. 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 function returns TRUE.

If the function fails, it returns FALSE.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

#pragma comment(lib, "crypt32.lib")
#include <iostream>
#include <windows.h>

int main()
{
	DATA_BLOB DataIn;
	DATA_BLOB DataOut;
	DATA_BLOB DataVerify;
	BYTE* pbDataInput = (BYTE*)"Hello world of data protection.";
	DWORD cbDataInput = strlen((char*)pbDataInput) + 1;
	DataIn.pbData = pbDataInput;
	DataIn.cbData = cbDataInput;
	LPWSTR pDescrOut = NULL;
	//-------------------------------------------------------------------
	//  Begin processing.
	printf("The data to be encrypted is: %s\n", pbDataInput);
	//-------------------------------------------------------------------
	//  Begin protect phase.
	if (CryptProtectData(
		&DataIn,
		L"This is the description string.", // A description string. 
		NULL,                               // Optional entropy
		NULL,                               // Reserved.
		NULL,                      // Pass a PromptStruct.
		0,
		&DataOut))
	{
		printf("The encryption phase worked. \n");
	}
	else
	{
		printf("Encryption error!");
	}
	//-------------------------------------------------------------------
	//   Begin unprotect phase.
	if (CryptUnprotectData(
		&DataOut,
		&pDescrOut,
		NULL,                 // Optional entropy
		NULL,                 // Reserved
		NULL,        // Optional PromptStruct
		0,
		&DataVerify))
	{
		printf("The decrypted data is: %s\n", DataVerify.pbData);
		printf("The description of the data was: %S\n", pDescrOut);
	}
	else
	{
		printf("Decryption error!");
	}
	//-------------------------------------------------------------------
	//  Clean up.
	LocalFree(pDescrOut);
	LocalFree(DataOut.pbData);
	LocalFree(DataVerify.pbData);
} // End of main

CryptProtectData()和CryptUnprotectData()在Windows.h头文件下，且函数依赖于crypt32.lib静态链接文件，使用前需将其都导入项目中。

加密的测试数据为“Hello world of data protection.”，上述函数的加密基于DATA_BLOB数据类型，其中pbData存储字节类型的数据，cbData为数据长度，且C++中BYTE*类型其实为unsigned char*类型，其长度比char*长一(多一个'\0')。