CryptUnprotectData 函式 (dpapi.h)

發行項
02/26/2024

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 結構的指標，其中包含加密數據時所使用的密碼或其他其他 Entropy。此參數可以設定為 NULL;不過，如果加密階段使用了選擇性的 entropy 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
程式庫	Crypt32.lib
Dll	Crypt32.dll