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： 不支持此标志。

返回值

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

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

返回代码 说明
STATUS_SUCCESS
 函数成功。
STATUS_NOT_FOUND
 找不到指定算法 ID 的提供程序。
STATUS_INVALID_PARAMETER
 一个或多个参数无效。
STATUS_NO_MEMORY
 内存分配失败。

注解

由于查找、加载和初始化算法提供程序所需的操作数量和类型， BCryptOpenAlgorithmProvider 函数是一个相对耗时的函数。 因此，建议缓存将多次使用的任何算法提供程序句柄，而不是一遍又一遍地打开和关闭算法提供程序。

可以从用户模式或内核模式调用 BCryptOpenAlgorithmProvider。 内核模式调用方必须在 IRQL PASSIVE_LEVEL 执行。

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

从 Windows 10 开始，CNG 不再遵循加密配置的每个更新。 某些更改（例如添加新的默认提供程序或更改算法提供程序的首选项顺序）可能需要重新启动。 因此，在使用任何新配置的提供程序调用 BCryptOpenAlgorithmProvider 之前，应重新启动。

要求

要求 值
最低受支持的客户端 Windows Vista [桌面应用 | UWP 应用]
最低受支持的服务器 Windows Server 2008 [桌面应用 | UWP 应用]
目标平台 Windows
标头 bcrypt.h
Library Bcrypt.lib
DLL Bcrypt.dll

另请参阅

BCryptCloseAlgorithmProvider