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結構的指標，其中包含用來加密資料的密碼或其他 Entropy。 加密階段中使用的 DATA_BLOB 結構也必須用於解密階段。 這個參數可以設定為 Null ，而沒有額外的 Entropy。 如需保護密碼的相關資訊，請參閱 處理密碼。

[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
程式庫 Crypt32.lib
Dll Crypt32.dll

另請參閱

CryptProtectMemory

CryptUnprotectData

資料加密和解密函式

LocalFree