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

此参数可以是以下标志之一。

值 含义
CRYPTPROTECT_LOCAL_MACHINE
 设置此标志后，它会将加密的数据与当前计算机（而不是单个用户）相关联。 调用 CryptProtectData 的计算机上的任何用户都可以使用 CryptUnprotectData 解密数据。
CRYPTPROTECT_UI_FORBIDDEN
 此标志用于无法显示用户界面 (UI) 的远程情况。 设置此标志并为保护或取消保护操作指定 UI 时，操作将失败， GetLastError 将返回ERROR_PASSWORD_RESTRICTION代码。
CRYPTPROTECT_AUDIT
 此标志生成有关保护和取消保护操作的审核。 仅当 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

另请参阅

CryptProtectMemory

CryptUnprotectData

数据加密和解密函数

LocalFree