CryptCreateHash 函式 (wincrypt.h)

發行項
03/03/2024

重要此 API 已被取代。新的和現有的軟體應該開始使用密碼編譯新一代 API。 Microsoft 可能會在未來的版本中移除此 API。

CryptCreateHash 函式會起始數據流的哈希。它會建立並傳回呼叫端應用程式對密碼編譯服務提供者的句柄， (CSP) 哈希物件。此句柄用於後續對 CryptHashData 和 CryptHashSessionKey 的呼叫，以哈希會話密鑰和其他數據流。

語法

BOOL CryptCreateHash(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  HCRYPTKEY  hKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTHASH *phHash
);

參數

[in] hProv

呼叫 CryptAcquireContext 所建立之 CSP 的句柄。

[in] Algid

識別要使用的哈希演算法的ALG_ID 值。

此參數的有效值會根據所使用的 CSP 而有所不同。如需預設演算法的清單，請參閱。

[in] hKey

如果哈希演算法的類型是索引哈希，例如哈希型訊息驗證碼 (HMAC) 或訊息驗證碼 (MAC) 演算法，則會在此參數中傳遞哈希的密鑰。對於非索引鍵演算法，此參數必須設定為零。

針對金鑰演演算法，金鑰必須是區塊加密金鑰，例如 RC2，其加密模式為加密區塊鏈結 (CBC) 。

[in] dwFlags

已定義下列旗標值。

值	意義
CRYPT_SECRETDIGEST 0x00000001	未使用這個旗標。

[out] phHash

函式將句柄複製到新哈希對象的位址。當您完成使用哈希物件時，請呼叫 CryptDestroyHash 函式來釋放句柄。

傳回值

如果函式成功，函式會傳回 TRUE。

如果函式失敗，則會傳回 FALSE。如需擴充的錯誤資訊，請呼叫 GetLastError。

NTE 開頭的錯誤碼是由您使用的特定 CSP 所產生。下表顯示一些可能的錯誤碼。

傳回碼	Description
ERROR_INVALID_HANDLE	其中一個參數指定無效的句柄。
ERROR_INVALID_PARAMETER	其中一個參數包含無效的值。這通常是無效的指標。
ERROR_NOT_ENOUGH_MEMORY	操作系統在作業期間記憶體不足。
NTE_BAD_ALGID	Algid 參數會指定此 CSP 不支持的演算法。
NTE_BAD_FLAGS	dwFlags 參數為非零。
NTE_BAD_KEY	algid 會指定索引鍵哈希演算法，例如 CALG_MAC，而 hKey 參數為零，或指定無效的密鑰句柄。如果索引鍵是數據流加密，或是加密模式不是 CBC，也會傳回這個錯誤碼。
NTE_NO_MEMORY	CSP 在作業期間記憶體不足。

備註

如需 Microsoft 服務提供者及其實作的演算法清單，請參閱 Microsoft 密碼編譯服務提供者。

實際哈希的計算是使用 CryptHashData 和 CryptHashSessionKey 函式來完成。這些需要哈希物件的句柄。將所有數據新增至哈希對象之後，即可執行下列任何作業：

您可以使用 CryptGetHashParam 來擷取哈希值。
會話密鑰可以使用 CryptDeriveKey 來衍生。
您可以使用 CryptSignHash 簽署哈希。
您可以使用 CryptVerifySignature 來驗證簽章。

呼叫此清單中的其中一個函式之後，就無法呼叫 CryptHashData 和 CryptHashSessionKey 。

範例

下列範例示範如何起始數據流的哈希。它會建立並傳回給呼叫端應用程式哈希物件的句柄。此句柄用於後續對 CryptHashData 和 CryptHashSessionKey 的呼叫，以哈希任何數據流。如需包含此範例完整內容的範例，請參閱範例 C 程式：建立和哈希會話密鑰。如需使用此函式的另一個範例，請參閱範例 C 程序：簽署哈希和驗證哈希簽章。

//--------------------------------------------------------------------
//  Declare variables.

HCRYPTPROV hCryptProv;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// Get a handle to a cryptography provider context.


if(CryptAcquireContext(
   &hCryptProv, 
   NULL, 
   NULL, 
   PROV_RSA_FULL, 
   0)) 
{
    printf("CryptAcquireContext complete. \n");
}
else
{
     printf("Acquisition of context failed.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Acquire a hash object handle.

if(CryptCreateHash(
   hCryptProv, 
   CALG_MD5, 
   0, 
   0, 
   &hHash)) 
{
    printf("An empty hash object has been created. \n");
}
else
{
    printf("Error during CryptBeginHash!\n");
    exit(1);
}

// Insert code that uses the hash object here.

//--------------------------------------------------------------------
// After processing, hCryptProv and hHash must be released.

if(hHash) 
   CryptDestroyHash(hHash);
if(hCryptProv) 
   CryptReleaseContext(hCryptProv,0);

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	wincrypt.h
程式庫	Advapi32.lib
Dll	Advapi32.dll