cryptCreateHash 函数 (wincrypt.h)

项目
08/27/2023

重要此 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) 算法，则哈希的密钥在此参数中传递。对于非密钥算法，此参数必须设置为零。

对于键式算法，该密钥必须是具有密码块链接 (CBC) 的密码模式的块加密密钥，例如 RC2。

[in] dwFlags

定义了以下标志值。

值	含义
CRYPT_SECRETDIGEST 0x00000001	未使用此标志。

[out] phHash

函数将句柄复制到新哈希对象的地址。使用完哈希对象后，通过调用 CryptDestroyHash 函数释放句柄。

返回值

如果函数成功，则函数返回 TRUE。

如果函数失败，则返回 FALSE。有关扩展的错误信息，请调用 GetLastError。

NTE 开头的错误代码由你使用的特定 CSP 生成。下表显示了一些可能的错误代码。

返回代码	说明
ERROR_INVALID_HANDLE	其中一个参数指定无效的句柄。
ERROR_INVALID_PARAMETER	其中一个参数包含无效的值。这通常是无效的指针。
ERROR_NOT_ENOUGH_MEMORY	操作系统在操作期间内存不足。
NTE_BAD_ALGID	Algid 参数指定此 CSP 不支持的算法。
NTE_BAD_FLAGS	dwFlags 参数为非零值。
NTE_BAD_KEY	键控哈希算法（如 CALG_MAC）由 Algid 指定， 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
Library	Advapi32.lib
DLL	Advapi32.dll