cryptUnprotectData 函数 (dpapi.h)

项目
08/23/2023

CryptUnprotectData 函数对DATA_BLOB结构中的数据进行解密并执行完整性检查。通常，唯一可以解密数据的用户是具有与加密数据的用户相同的登录凭据的用户。此外，加密和解密必须在同一台计算机上完成。有关异常的信息，请参阅 CryptProtectData 的“备注”部分。

语法

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

参数

[in] pDataIn

指向保存加密数据的 DATA_BLOB 结构的指针。 DATA_BLOB 结构的 cbData 成员包含要加密的文本的 pbData 成员的字节字符串的长度。

[out, optional] ppszDataDescr

指向加密数据中包含的加密数据的字符串可读说明的指针。此参数可以设置为 NULL。使用 完 ppszDataDescr 后，通过调用 LocalFree 函数将其释放。

[in, optional] pOptionalEntropy

指向 DATA_BLOB 结构的指针，该结构包含加密数据时使用的密码或其他附加信息量。此参数可以设置为 NULL;但是，如果在加密阶段使用了可选的熵 DATA_BLOB 结构，则必须对解密阶段使用相同的 DATA_BLOB 结构。有关保护密码的信息，请参阅处理密码。

pvReserved

此参数保留供将来使用，必须设置为 NULL。

[in, optional] pPromptStruct

指向 CRYPTPROTECT_PROMPTSTRUCT 结构的指针，该结构提供有关显示提示的位置和时间以及这些提示的内容的信息。此参数可以设置为 NULL。

[in] dwFlags

指定此函数的选项的 DWORD 值。此参数可以为零（在这种情况下未设置任何选项）或以下标志。

值	含义
CRYPTPROTECT_UI_FORBIDDEN	此标志用于用户界面 (UI) 不是选项的远程情况。如果设置了此标志，并且为保护或取消保护操作指定了 UI，则操作将失败，并且 GetLastError 将返回ERROR_PASSWORD_RESTRICTION代码。
CRYPTPROTECT_VERIFY_PROTECTION	此标志验证受保护 BLOB 的保护。如果主机配置的默认保护级别高于 BLOB 的当前保护级别，该函数将返回 CRYPT_I_NEW_PROTECTION_REQUIRED ，以建议调用方再次保护 BLOB 中包含的纯文本。

[out] pDataOut

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

返回值

如果函数成功，则函数返回 TRUE。

如果函数失败，则返回 FALSE。

注解

加密数据时，CryptProtectData 函数会创建会话密钥。该密钥再次派生并用于解密数据 BLOB。

添加到加密数据的消息身份验证代码 (MAC) 哈希可用于确定是否以任何方式更改了加密数据。任何篡改都会导致返回ERROR_INVALID_DATA代码。

使用完 DATA_BLOB 结构后，通过调用 LocalFree 函数释放其 pbData 成员。任何不为 NULL 的 ppszDataDescr 也必须使用 LocalFree 释放。

使用完敏感信息后，通过调用 SecureZeroMemory 函数将其从内存中清除。

示例

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

// Decrypt data from DATA_BLOB DataOut to DATA_BLOB DataVerify.

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

DATA_BLOB DataOut;
DATA_BLOB DataVerify;
LPWSTR pDescrOut =  NULL;
//--------------------------------------------------------------------
// The buffer DataOut would be created using the CryptProtectData
// function. If may have been read in from a file.

//--------------------------------------------------------------------
//   Begin unprotect phase.

if (CryptUnprotectData(
        &DataOut,
        &pDescrOut,
        NULL,                 // Optional entropy
        NULL,                 // Reserved
        NULL,                 // Here, the optional 
                              // prompt structure is not
                              // used.
        0,
        &DataVerify))
{
     printf("The decrypted data is: %s\n", DataVerify.pbData);
     printf("The description of the data was: %s\n",pDescrOut);
     LocalFree(DataVerify.pbData);
     LocalFree(pDescrOut);
}
else
{
    printf("Decryption error!");
}

要求

要求	值
最低受支持的客户端	Windows XP [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	dpapi.h
Library	Crypt32.lib
DLL	Crypt32.dll