BCryptCreateMultiHash 函式 (bcrypt.h)

發行項
02/23/2024

BCryptCreateMultiHash 函式會建立多重哈希狀態，允許平行計算多個哈希作業。 BCryptProcessMultiOperations 函式會使用此多重哈希狀態。多哈希狀態可以視為哈希對象的陣列，每個都相當於 BCryptCreateHash 所建立的哈希物件陣列。

平行計算可以大幅增加整體輸送量，但代價是個別計算的延遲增加。

平行哈希計算目前僅針對SHA-256、SHA-384和SHA-512實作。其他哈希演算法可以搭配平行計算 API 使用，但它們會在循序哈希作業的輸送量上執行。可受益於平行計算的哈希演算法集合，在未來的更新中可能會變更。

語法

NTSTATUS BCryptCreateMultiHash(
  BCRYPT_ALG_HANDLE  hAlgorithm,
  BCRYPT_HASH_HANDLE *phHash,
  ULONG              nHashes,
  PUCHAR             pbHashObject,
  ULONG              cbHashObject,
  PUCHAR             pbSecret,
  ULONG              cbSecret,
  ULONG              dwFlags
);

參數

hAlgorithm

BCRYPT_ALG_HANDLE[in, out]

用於多哈希陣列中所有哈希狀態的演算法句柄。演算法句柄必須以傳遞至 BCryptOpenAlgorithmProvider 函式的 BCYRPT_MULTI_FLAG開啟。或者，呼叫端可以使用虛擬句柄。

phHash

BCRYPT_HASH_HANDLE* [out]

BCRYPT_HASH_HANDLE值的指標，接收代表多重哈希狀態的句柄。此句柄用於後續的作業，例如 BCryptProcessMultiOperations。當您完成使用此句柄時，請將它傳遞至 BCryptDestroyHash 函式來釋放它。

nHashes

ULONG[in]

陣列中的項目數。此函式所建立的多哈希狀態能夠在 nHashes 不同的哈希狀態上執行平行計算。

pbHashObject

PUCHAR[out]

接收多重哈希狀態之緩衝區的指標。

大小可以從BCRYPT_MULTI_OBJECT_LENGTH_STRUCT結構的 cbPerObject 和 cbPerElement 成員計算。此值如下： cbPerObject + (number of hash states) * cbPerElement。

如果 pbHashObject 為 NULL ，且 cbHashObject 的值為零 (0) ，則會自動配置物件緩衝區。

cbHashObject

ULONG[in]

pbHashObject 緩衝區的大小，如果 pbHashObject 為 NULL，則為零 (0) 。

pbSecret

PUCHAR[in]

緩衝區的指標，其中包含要用於哈希或MAC的索引鍵。 cbSecret 參數包含此緩衝區的大小。此密鑰僅適用於 BCryptOpenAlgorithmProvider 函式使用 BCRYPT_ALG_HANDLE_HMAC 旗標所開啟的哈希演算法。否則，請將此參數設定為 NULL。

相同的索引鍵會用於數位的所有元素。

cbSecret

ULONG[in]

pbSecret 緩衝區的大小，以位元組為單位。如果未使用任何索引鍵，請將此參數設定為零 (0) 。

dwFlags

ULONG[in]

修改函式行為的旗標。這可以是零或下列值。多哈希物件一律可重複使用，且一律會像傳遞 BCRYPT_HASH_REUSABLE_FLAG 一樣。這裡支援此旗標以取得一致性。

值	意義
BCRYPT_HASH_REUSABLE_FLAG	建立可重複使用的哈希物件。呼叫 BCryptFinishHash 之後，物件可以立即用於新的哈希作業。如需詳細資訊，請參閱使用 CNG 建立哈希。

傳回值

傳回狀態代碼，指出函式的成功或失敗。如果方法成功，則會傳回 STATUS_SUCCESS。如需其他 NTSTATUS 值，請參閱 NTSTATUS值。

備註

在內部，平行哈希計算是使用單一指令多重數據 (SIMD) 指令，一次最多 8 個平行計算，視哈希演算法和可用的 CPU 功能而定。若要將效能最大化，建議呼叫端提供至少八個可平行處理的計算。

針對長度不相等的計算，以平行方式提供更多計算，可讓實作在 CPU 快存器上更妥善地排程計算。這可以提供輸送量優勢。為了獲得最佳輸送量，我們建議呼叫端提供介於8到100個計算之間。只有在所有哈希計算都是相同的長度時，才選取該範圍中的較低值。

HMAC-MD2、HMAC-MD4 和 GMAC 不支援多重哈希。

規格需求

需求	值
最低支援的用戶端	Windows 8.1 更新版 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 Update [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	bcrypt.h
程式庫	Bcrypt.lib
Dll	Bcrypt.dll