CryptProtectData 函数 （dpapi.h）

CryptProtectData 函数对DATA_BLOB结构中的数据执行加密。 通常，只有与加密数据的用户具有相同登录凭据的用户才能解密数据。 此外，加密和解密通常必须在同一台计算机上完成。 有关异常的信息，请参阅 “备注”。

Syntax

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

参数

[in] pDataIn

指向包含要加密的纯文本的DATA_BLOB结构的指针。

[in, optional] szDataDescr

一个字符串，其中包含要加密的数据的可读说明。 此说明字符串包含在加密数据中。 此参数是可选的，可以设置为 NULL。

[in, optional] pOptionalEntropy

指向 DATA_BLOB 结构的指针，该结构包含用于加密数据的密码或其他附加信息量。 加密阶段中使用的 DATA_BLOB 结构也必须在解密阶段使用。 此参数可设置为 NULL ，不需额外获取任何信息量。 有关保护密码的信息，请参阅 “处理密码”。

[in] pvReserved

保留以供将来使用，必须设置为 NULL。

[in, optional] pPromptStruct

指向 CRYPTPROTECT_PROMPTSTRUCT 结构的指针，该结构提供有关要显示提示的位置和时间以及这些提示的内容。 可以在加密和解密阶段将此参数设置为 NULL 。

[in] dwFlags

此参数可以是以下标志之一。 如果不需要任何标志，则可以将此参数设置为 0。

[out] pDataOut

指向接收加密数据的 DATA_BLOB 结构的指针。 使用完DATA_BLOB结构后，通过调用 LocalFree 函数释放其 pbData 成员。

返回值

如果函数成功，该函数将返回 TRUE。

如果函数失败，则返回 FALSE。 有关扩展错误信息，请调用 GetLastError。

注解

通常，只有具有与加密数据的用户匹配的登录 凭据 的用户才能解密数据。 此外，解密通常只能在加密数据的计算机上完成。 但是，具有漫游配置文件的用户可以从网络上的另一台计算机解密数据。

如果在加密数据时设置了 CRYPTPROTECT_LOCAL_MACHINE 标志，则完成加密的计算机上的任何用户都可以解密数据。

该函数创建会话密钥来执行加密。 在解密数据时，会话密钥将再次派生。

该函数还会向加密数据添加 消息身份验证代码 （MAC）（密钥完整性检查），以防止数据篡改。

若要加密内存以便在同一进程中或跨进程使用，请调用 CryptProtectMemory 函数。

例子

以下示例演示 DATA_BLOB 结构中的数据加密。 CryptProtectData 函数通过使用用户登录凭据创建的会话密钥执行加密。 有关使用此函数的另一个示例，请参阅 示例 C 程序：使用 CryptProtectData。

// Encrypt data from DATA_BLOB DataIn to DATA_BLOB DataOut.

//--------------------------------------------------------------------
// Declare and initialize variables.

DATA_BLOB DataIn;
DATA_BLOB DataOut;
BYTE *pbDataInput =(BYTE *)"Hello world of data protection.";
DWORD cbDataInput = strlen((char *)pbDataInput)+1;

//--------------------------------------------------------------------
// Initialize the DataIn structure.

DataIn.pbData = pbDataInput;    
DataIn.cbData = cbDataInput;

//--------------------------------------------------------------------
//  Begin protect phase. Note that the encryption key is created
//  by the function and is not passed.

if(CryptProtectData(
     &DataIn,
     L"This is the description string.", // A description string
                                         // to be included with the
                                         // encrypted data. 
     NULL,                               // Optional entropy not used.
     NULL,                               // Reserved.
     NULL,                               // Pass NULL for the 
                                         // prompt structure.
     0,
     &DataOut))
{
     printf("The encryption phase worked.\n");
     LocalFree(DataOut.pbData);
}
else
{
    printf("Encryption error using CryptProtectData.\n");
    exit(1); 
}

要求

另请参阅

• CryptProtectMemory
• CryptUnprotectData
• 数据加密和解密函数
• LocalFree