BCryptCreateMultiHash 函数 (bcrypt.h)

项目
02/26/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]

用于多哈希数组中所有哈希状态的算法句柄。算法句柄必须已打开， BCYRPT_MULTI_FLAG 传递给 BCryptOpenAlgorithmProvider 函数。或者，调用方可以使用伪句柄。

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 更新 [桌面应用 \|UWP 应用]
目标平台	Windows
标头	bcrypt.h
Library	Bcrypt.lib
DLL	Bcrypt.dll