BCryptCreateHash 函数 （bcrypt.h）

调用 BCryptCreateHash 函数来创建哈希或 消息身份验证代码 （MAC） 对象。

语法

NTSTATUS BCryptCreateHash(
  [in, out]       BCRYPT_ALG_HANDLE  hAlgorithm,
  [out]           BCRYPT_HASH_HANDLE *phHash,
  [out, optional] PUCHAR             pbHashObject,
  [in]            ULONG              cbHashObject,
  [in, optional]  PUCHAR             pbSecret,
  [in]            ULONG              cbSecret,
  [in]            ULONG              dwFlags
);

参数

[in, out] hAlgorithm

支持哈希或 MAC 接口的算法提供程序的句柄。 此句柄是通过调用 BCryptOpenAlgorithmProvider 函数获取的，也可以是 CNG 算法伪句柄。

[out] phHash

指向 BCRYPT_HASH_HANDLE 值的指针，该值接收表示哈希或 MAC 对象的句柄。 此句柄用于后续哈希或 MAC 函数，例如 BCryptHashData 函数。 使用此句柄后，请将其传递给 BCryptDestroyHash 函数来释放它。

[out, optional] pbHashObject

指向接收哈希或 MAC 对象的缓冲区的指针。 cbHashObject 参数包含此缓冲区的大小。 可以通过调用 BCryptGetProperty 函数从算法句柄获取 BCRYPT_OBJECT_LENGTH 属性来获取此缓冲区的所需大小。 这将为指定的算法提供哈希或 MAC 对象的大小。

只有在 phHash 参数指向的句柄被销毁后，才能释放此内存。

如果此参数 NULL 的值和 cbHashObject 参数的值为零，则哈希对象的内存由此函数分配，并由 BCryptDestroyHash 释放。 Windows 7： 从 Windows 7 开始，可以使用此内存管理功能。

[in] cbHashObject

pbHashObject 缓冲区的大小（以字节为单位）。

如果此参数的值为零且 pbHashObject 参数的值为 NULL，则密钥对象的内存由此函数分配，并由 BCryptDestroyHash 释放。 Windows 7： 从 Windows 7 开始，可以使用此内存管理功能。

[in, optional] pbSecret

指向包含用于 MAC 的密钥的缓冲区的指针。 cbSecret 参数包含此缓冲区的大小。 如果与哈希算法一起使用，则必须使用 BCryptOpenAlgorithmProvider 中的 BCRYPT_ALG_HANDLE_HMAC 标志将算法提升到 HMAC。

若要计算哈希，请将此参数设置为 NULL。

[in] cbSecret

pbSecret 缓冲区的大小（以字节为单位）。 如果未使用任何键，请将此参数设置为零。

[in] dwFlags

修改函数行为的标志。 此值可以为零或以下值：

返回值

返回一个状态代码，指示函数的成功或失败。

可能的返回代码包括但不限于以下代码。

言论

使用支持的算法提供程序时，可以从用户模式或内核模式调用 BCryptCreateHash 。 内核模式调用方可以在 IRQL PASSIVE_LEVEL 或 DISPATCH_LEVELIRQL 上执行。 如果当前 IRQL 级别DISPATCH_LEVEL，则必须使用 BCRYPT_PROV_DISPATCH 标志打开 hAlgorithm 参数中提供的句柄，并且传递给 BCryptCreateHash 函数的任何指针都必须引用非分页（或锁定）内存。

当对象不再使用时，调用方应释放具有 BCryptDestroyHash 的 phHash。

若要在内核模式下调用此函数，请使用 Cng.lib，这是驱动程序开发工具包（DDK）的一部分。 Windows Server 2008 和 Windows Vista： 若要在内核模式下调用此函数，请使用 Ksecdd.lib。

要求

另请参阅

BCryptDuplicateHash

BCryptHashData

BCryptFinishHash

BCryptDestroyHash