CryptUnprotectData 函式（dpapi.h）

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 值。此參數可以是零，在此情況下不會設定任何選項，或下列旗標。

價值觀	Meaning
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、ERROR_INVALID_PARAMETER，或在某些情況下可能會成功處理損毀的輸出。應用程式不應依賴特定的錯誤碼來偵測資料竄改。為了實現強大的篡改檢測，請考慮在應用程式層級實施額外的完整性檢查。

當您完成使用 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!");
}

需求

Requirement	價值觀
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平臺	窗戶
Header	dpapi.h
Library	地穴32.lib
DLL	Crypt32.dll