BCryptOpenAlgorithmProvider 函式 (bcrypt.h)

  • 發行項

BCryptOpenAlgorithmProvider 函式會載入並初始化 CNG 提供者。

語法

NTSTATUS BCryptOpenAlgorithmProvider(
  [out] BCRYPT_ALG_HANDLE *phAlgorithm,
  [in]  LPCWSTR           pszAlgId,
  [in]  LPCWSTR           pszImplementation,
  [in]  ULONG             dwFlags
);

參數

[out] phAlgorithm

接收 CNG 提供者句柄 之BCRYPT_ALG_HANDLE 變數的指標。 當您完成使用此句柄時，請將它傳遞至 BCryptCloseAlgorithmProvider 函式來釋放它。

[in] pszAlgId

識別所要求密碼編譯演算法之 Null 終止 Unicode 字串的指標。 這可以是其中一個標準 CNG 演演算法標識碼 ，或是另一個已註冊演算法的標識碼。

[in] pszImplementation

識別要載入之特定提供者之 Null 終止 Unicode 字串的指標。 這是密碼編譯基本提供者的已註冊別名。 此參數是選擇性的，如果不需要，它可以是 NULL 。 如果此參數為 NULL，將會載入指定演算法的預設提供者。

注意 如果 pszImplementation 參數值為 NULL，CNG 會針對 pszAlgId 參數指定的演算法嘗試開啟每個已註冊的提供者，並傳回成功開啟之第一個提供者的句柄。 在句柄的存留期內，任何 BCrypt** 密碼編譯 API 都會使用已成功開啟的提供者。
 
Windows Server 2008 和 Windows Vista： CNG 嘗試回復至 Microsoft CNG 提供者。

以下是預先定義的提供者名稱。

值 意義
MS_PRIMITIVE_PROVIDER
“Microsoft Primitive Provider”
 識別基本的 Microsoft CNG 提供者。
MS_PLATFORM_CRYPTO_PROVIDER
L“Microsoft Platform Crypto Provider”
 識別 Microsoft 提供的 TPM 金鑰儲存提供者。

[in] dwFlags

修改函式行為的旗標。 這可以是零或下列一或多個值的組合。

值 意義
BCRYPT_ALG_HANDLE_HMAC_FLAG
 提供者會使用指定的哈希演算法，執行 哈希型訊息驗證碼 (HMAC) 演算法。 此旗標僅供哈希演算法提供者使用。
BCRYPT_PROV_DISPATCH
 將提供者載入非分頁記憶體集區。 如果這個旗標不存在，提供者就會載入分頁記憶體集區。 指定此旗標時，在釋放所有相依物件之前，不得關閉傳回的句柄。
注意 此旗標僅在核心模式中受到支援，並允許在分派層級處理提供者上的後續作業。 如果提供者不支援在分派層級呼叫，則會在使用這個旗標開啟時傳回錯誤。
 
Windows Server 2008 和 Windows Vista： 此旗標僅受 Microsoft 演算法提供者支援，僅適用於 哈希演算法 和 對稱密鑰密碼編譯演算法。
BCRYPT_HASH_REUSABLE_FLAG
 建立可重複使用的哈希物件。 對象可以在呼叫 BCryptFinishHash 之後立即用於新的哈希作業。 如需詳細資訊，請參閱 使用 CNG 建立哈希。

Windows Server 2008 R2、Windows 7、Windows Server 2008 和 Windows Vista： 不支援此旗標。

傳回值

傳回狀態代碼，指出函式的成功或失敗。

可能的傳回碼包括但不限於下列各項。

傳回碼 Description
STATUS_SUCCESS
 函式成功。
STATUS_NOT_FOUND
 找不到指定演算法識別碼的提供者。
STATUS_INVALID_PARAMETER
 一或多個參數無效。
STATUS_NO_MEMORY
 發生記憶體配置失敗。

備註

由於尋找、載入和初始化演算法提供者所需的作業數目和類型， 因此 BCryptOpenAlgorithmProvider 函式是相當耗時的函式。 因此，我們建議您快取任何演算法提供者句柄，而您將使用多次，而不是開啟和關閉演算法提供者。

BCryptOpenAlgorithmProvider 可以從使用者模式或核心模式呼叫。 核心模式呼叫端必須在 PASSIVE_LEVELIRQL 上執行。

若要在核心模式中呼叫此函式，請使用 Cng.lib，這是驅動程式開發工具包 (DDK) 的一部分。 Windows Server 2008 和 Windows Vista： 若要在核心模式中呼叫此函式，請使用 Ksecdd.lib。

從 Windows 10 開始，CNG 不再遵循密碼編譯組態的每個更新。 某些變更，例如新增預設提供者或變更演算法提供者的喜好設定順序，可能需要重新啟動。 因此，您應該先重新啟動，再呼叫 BCryptOpenAlgorithmProvider 與任何新設定的提供者。

規格需求

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

另請參閱

BCryptCloseAlgorithmProvider