CryptProtectData 函数 (dpapi.h)
CryptProtectData 函数对DATA_BLOB结构中的数据执行加密。 通常,只有与加密数据的用户具有相同登录凭据的用户才能解密数据。 此外,通常必须在同一台计算机上完成加密和解密。 有关异常的信息,请参阅备注。
语法
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
此参数可以是以下标志之一。
值 | 含义 |
---|---|
|
设置此标志后,它会将加密的数据与当前计算机(而不是单个用户)相关联。 调用 CryptProtectData 的计算机上的任何用户都可以使用 CryptUnprotectData 解密数据。 |
|
此标志用于无法显示用户界面 (UI) 的远程情况。 设置此标志并为保护或取消保护操作指定 UI 时,操作将失败, GetLastError 将返回ERROR_PASSWORD_RESTRICTION代码。 |
|
此标志生成有关保护和取消保护操作的审核。 仅当 szDataDescr 不为 NULL 且不为空时,才会记录审核日志条目。 |
[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);
}
要求
最低受支持的客户端 | Windows XP [桌面应用 | UWP 应用] |
最低受支持的服务器 | Windows Server 2003 [桌面应用 | UWP 应用] |
目标平台 | Windows |
标头 | dpapi.h |
Library | Crypt32.lib |
DLL | Crypt32.dll |