會呼叫 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 釋放。
視窗7： 此記憶體管理功能從 Windows 7 開始可用。
[in] cbHashObject
pbHashObject 緩衝區的大小 （以位元組為單位）。
如果此參數的值為零，而 pbHashObject 參數的值為 NULL，則索引鍵物件的記憶體會由此函式配置，並由 BCryptDestroyHash 釋放。
視窗7： 此記憶體管理功能從 Windows 7 開始可用。
[in, optional] pbSecret
緩衝區的指標，其中包含要用於 MAC 的金鑰。 cbSecret 參數包含此緩衝區的大小。 如果與雜湊演算法搭配使用，則演算法必須已使用 BCryptOpenAlgorithmProvider 中的 BCRYPT_ALG_HANDLE_HMAC 旗標升級為 HMAC。
若要計算雜湊，請將此參數設定為 NULL。
[in] cbSecret
pbSecret 緩衝區的大小 （以位元組為單位）。 如果未使用任何索引鍵，請將此參數設定為零。
[in] dwFlags
修改函式行為的旗標。 這可以是零或下列值：
| 價值 | 意義 |
|---|---|
| BCRYPT_HASH_REUSABLE_FLAG | 建立可重複使用的哈希物件。 物件可以在呼叫 BCryptFinishHash 之後立即用於新的雜湊作業。 如需詳細資訊，請參閱 使用 CNG 建立雜湊。 Windows Server 2008 R2、Windows 7、Windows Server 2008 和 Windows Vista： 不支援此旗標。 |
傳回值
傳回狀態代碼，指出函式的成功或失敗。
可能的傳回碼包括，但不限於下列專案。
| 傳回碼 | 描述 |
|---|---|
| STATUS_SUCCESS | 函式成功。 |
| STATUS_BUFFER_TOO_SMALL | cbHashObject 參數所指定的雜湊物件大小不足以容納雜湊物件。 |
| STATUS_INVALID_HANDLE | hAlgorithm 參數中的演算法控制碼無效。 |
| STATUS_INVALID_PARAMETER | 一或多個參數無效。 |
| STATUS_NOT_SUPPORTED | hAlgorithm 參數指定的演算法提供者不支援雜湊或 MAC 介面。 |
言論
使用支援的演算法提供者時，可以從使用者模式或核心模式呼叫 BCryptCreateHash 。 核心模式呼叫端可以在 PASSIVE_LEVELIRQL 或 DISPATCH_LEVEL IRQL 執行。 如果目前的 IRQL 層級DISPATCH_LEVEL，則必須使用 BCRYPT_PROV_DISPATCH 旗標開啟 hAlgorithm 參數中提供的控制碼，而且傳遞至 BCryptCreateHash 函式的任何指標都必須參考非分頁 （或鎖定） 記憶體。
呼叫端應該在物件不再使用時使用 BCryptDestroyHash 釋放 phHash。
若要在核心模式中呼叫此函式，請使用 Cng.lib，這是驅動程式開發套件 （DDK） 的一部分。
Windows Server 2008 和 Windows Vista： 若要在核心模式中呼叫此函式，請使用 Ksecdd.lib。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 支援的最低伺服器 | Windows Server 2008 [傳統型應用程式 |UWP 應用程式] |
| 目標平臺 | 窗戶 |
| Header | bcrypt.h |
| Library | Bcrypt.lib |
| DLL | Bcrypt.dll |