NCryptTranslateHandle 函数 (ncrypt.h)

  • 项目

NCryptTranslateHandle 函数将 CryptoAPI 句柄转换为 CNG 密钥句柄。

语法

SECURITY_STATUS NCryptTranslateHandle(
  [out, optional] NCRYPT_PROV_HANDLE *phProvider,
  [out]           NCRYPT_KEY_HANDLE  *phKey,
  [in]            HCRYPTPROV         hLegacyProv,
  [in, optional]  HCRYPTKEY          hLegacyKey,
  [in, optional]  DWORD              dwLegacyKeySpec,
  [in]            DWORD              dwFlags
);

参数

[out, optional] phProvider

指向 NCRYPT_PROV_HANDLE 变量的指针，该变量接收 CNG 密钥存储提供程序的句柄，该提供程序拥有 放置在 phKey 参数中的 CNG 密钥。 如果不需要此句柄，此参数可以为 NULL 。

[out] phKey

指向接收 CNG 键句柄 的NCRYPT_KEY_HANDLE 变量的指针。

[in] hLegacyProv

包含要转换的密钥的 CryptoAPI 提供程序的句柄。 此函数将转换此提供程序中容器中的 CryptoAPI 密钥。

[in, optional] hLegacyKey

用于帮助确定返回密钥的密钥规范的 CryptoAPI 密钥的句柄。 如果 dwLegacyKeySpec 参数包含非零值，则忽略此参数。

如果 hLegacyKey 为 NULL 且 dwLegacyKeySpec 为零，则此函数将尝试从 hLegacyProv 句柄确定密钥规范。

[in, optional] dwLegacyKeySpec

指定密钥的密钥规范。 这可以是以下值之一。

值 含义
0
 键不是以下类型。
AT_KEYEXCHANGE
1
 密钥是密钥交换密钥。
AT_SIGNATURE
2
 密钥是签名密钥。
 

如果 hLegacyKey 为 NULL 且 dwLegacyKeySpec 为零，则此函数将尝试从 hLegacyProv 句柄确定密钥规范。

[in] dwFlags

一组标志，用于修改此函数的行为。 未为此函数定义任何标志。

返回值

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

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

返回代码 说明
ERROR_SUCCESS
 函数成功。
NTE_BAD_FLAGS
 dwFlags 参数包含无效的值。
NTE_INVALID_PARAMETER
 一个或多个参数无效。
NTE_NO_MEMORY
 内存分配失败。

注解

这是一个帮助程序函数，旨在帮助当前使用 CryptoAPI 的应用程序和系统组件正常过渡到使用 CNG。

仅当 CNG 密钥存储提供程序注册的名称或别名与 hLegacyProv 参数引用的加密服务提供程序 (CSP) 的名称相同时，此函数才会成功。

此函数将执行以下步骤，将 CSP 句柄转换为 CNG 密钥句柄：

  1. 从 hLegacyProv 句柄获取 CSP 的名称。
  2. 打开其名称或别名与 CSP 名称相同的 CNG 提供程序。
  3. 获取 CSP 中当前密钥容器的名称。
  4. 获取 CryptoAPI 密钥，将其转换为 CNG 密钥，并在 phKey 参数中返回。
服务不得从其 StartService 函数调用此函数。 如果服务从其 StartService 函数调用此函数，则可能会出现死锁，并且服务可能会停止响应。

要求

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