NCryptImportKey 函数 (ncrypt.h)

  • 项目

NCryptImportKey 函数从内存 BLOB 导入加密 API：下一代 (CNG) 密钥。

语法

SECURITY_STATUS NCryptImportKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [in, optional] NCRYPT_KEY_HANDLE  hImportKey,
  [in]           LPCWSTR            pszBlobType,
  [in, optional] NCryptBufferDesc   *pParameterList,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           PBYTE              pbData,
  [in]           DWORD              cbData,
  [in]           DWORD              dwFlags
);

参数

[in] hProvider

密钥存储提供程序的句柄。

[in, optional] hImportKey

加密密钥的句柄，用于加密导入的 密钥BLOB 中的密钥 数据。 这必须是在 NCryptExportKey 函数的 hExportKey 参数中传递的同一密钥的句柄。 如果此参数为 NULL，则假定密钥 BLOB 未加密。

[in] pszBlobType

一个以 null 结尾的 Unicode 字符串，其中包含指定密钥 BLOB 格式的标识符。 这些格式特定于特定的密钥存储提供程序。 有关 Microsoft 提供程序支持的 BLOB 格式，请参阅备注。

[in, optional] pParameterList

NCryptBufferDesc 结构的地址，该结构指向包含密钥的参数信息的缓冲区数组。

[out] phKey

接收密钥句柄 的NCRYPT_KEY_HANDLE 变量的地址。 完成使用此句柄后，将其传递给 NCryptFreeObject 函数以释放它。

[in] pbData

包含要导入的密钥 BLOB 的缓冲区的地址。 cbData 参数包含此缓冲区的大小。

[in] cbData

pbData 缓冲区的大小（以字节为单位）。

[in] dwFlags

修改函数行为的标志。 这可以是零，也可以是以下一个或多个值的组合。 有效标志集特定于每个密钥存储提供程序。

值 含义
NCRYPT_SILENT_FLAG 请求关键服务提供程序 (KSP) 不显示任何用户界面。 如果提供程序必须显示 UI 才能运行，则调用会失败，KSP 应将 NTE_SILENT_CONTEXT 错误代码设置为最后一个错误。
NCRYPT_REQUIRE_VBS_FLAG 指示必须使用基于虚拟化的安全 (VBS) 保护密钥。

如果 VBS 不可用，操作将失败。 (*请参阅备注)
NCRYPT_PREFER_VBS_FLAG 指示应使用基于虚拟化的安全性 (VBS) 保护密钥。

如果 VBS 不可用，操作将生成软件隔离密钥。 (*请参阅备注)

返回值

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

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

返回代码 说明
ERROR_SUCCESS 函数成功。
NTE_BAD_FLAGS dwFlags 参数包含无效的值。
NTE_EXISTS 具有指定名称的键已存在，并且未指定 NCRYPT_OVERWRITE_KEY_FLAG 。
NTE_INVALID_HANDLE hProvider 参数无效。
NTE_INVALID_PARAMETER 一个或多个参数无效。
NTE_NO_MEMORY 发生内存分配失败。
NTE_VBS_UNAVAILABLE VBS 不可用。
NTE_VBS_CANNOT_DECRYPT_KEY VBS 解密操作失败。

注解

重要

有关 VBS 标志的信息与在商业发布之前可能进行重大修改的预发布产品有关。 对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

服务不得从其 StartService 函数调用此函数。 如果服务从其 StartService 函数调用此函数，则可能会出现死锁，并且服务可能会停止响应。

以下部分介绍特定于 Microsoft 密钥存储提供程序的行为：

  • Microsoft Software KSP
  • Microsoft 智能卡 KSP

Microsoft Software KSP

对于 pszBlobType 参数，Microsoft 软件 KSP 支持以下常量。

如果未提供密钥名称，Microsoft Software KSP 会将密钥视为临时密钥，并且不会永久存储它。 对于 NCRYPT_OPAQUETRANSPORT_BLOB 类型，密钥名称在导出时存储在 BLOB 中。 对于其他 BLOB 格式，可以在 pParameterList 参数内的 NCRYPTBUFFER_PKCS_KEY_NAME 缓冲区参数中提供该名称。

在 Windows Server 2008 和 Windows Vista 上，只有导入为 PKCS #7 信封 BLOB 的密钥 (NCRYPT_PKCS7_ENVELOPE_BLOB) 或 PKCS #8 私钥 BLOB (NCRYPT_PKCS8_PRIVATE_KEY_BLOB) 可以使用上述方法持久保存。 若要在这些平台上保留通过其他 BLOB 类型导入的密钥，请使用 密钥导入和导出中记录的方法。

此 KSP 支持以下标志。

术语 说明
NCRYPT_NO_KEY_VALIDATION 不要验证密钥对的公共部分。 此标志仅适用于公钥/私钥对。
NCRYPT_DO_NOT_FINALIZE_FLAG 请勿完成密钥。 在导入密钥后需要添加或修改密钥的属性时，此选项非常有用。 必须先完成密钥，然后才能通过将密钥句柄传递给 NCryptFinalizeKey 函数来使用它。 私钥 PKCS #7 和 PKCS #8 支持此标志，但不支持公钥。
NCRYPT_MACHINE_KEY_FLAG 密钥适用于本地计算机。 如果此标志不存在，则密钥将应用于当前用户。
NCRYPT_OVERWRITE_KEY_FLAG 如果容器中已存在具有指定名称的密钥，则会覆盖现有密钥。 如果未指定此标志，并且已存在具有指定名称的键，则此函数将返回 NTE_EXISTS。
NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG 此外，请将密钥保存在旧存储中。 这允许将密钥与 CryptoAPI 一起使用。 此标志仅适用于 RSA 密钥。

Microsoft 智能卡 KSP

此 KSP 支持的关键 BLOB 格式和标志集与 Microsoft Software KSP 支持的集相同。

在 Windows Server 2008 和 Windows Vista 上，Microsoft 智能卡 KSP 将所有密钥导入 Microsoft Software KSP。 因此，使用此 API 无法将密钥保存到智能卡，并且尝试在 Microsoft Software KSP 中保存密钥时，上述部分中的指南适用。

在 Windows Server 2008 R2 和 Windows 7 上，如果满足以下条件，Microsoft 智能卡密钥存储提供程序可以将私钥导入智能卡：

  • 卡上的密钥容器名称有效。
  • 智能卡支持导入私钥。
  • 以下两个注册表项设置为 的 0x1DWORD：
    • HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateExchangeKeyImport
    • HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateSignatureKeyImport

如果密钥容器名称为 NULL，Microsoft 智能卡 KSP 会将密钥视为临时密钥，并将其导入 Microsoft Software KSP。

VBS 密钥的其他硬件要求

尽管计算机上可能安装了相应的 OS，但必须满足以下附加硬件要求才能使用 VBS 生成和保护密钥。

  • 已启用 VBS (请参阅 基于虚拟化的安全性 (VBS) )
  • 已启用 TPM
    • 对于裸机环境，需要 TPM 2.0。
    • 对于 VM 环境，支持 vTPM (虚拟 TPM) 。
  • BIOS 应使用 SecureBoot 配置文件升级到 UEFI

有关硬件要求的详细信息：

  • VBS 需要运行多个硬件要求，包括 Hyper-V (Windows 虚拟机监控程序) 、64 位体系结构和 IOMMU 支持。 可以 在此处找到 VBS 硬件要求的完整列表。
  • 可 在此处找到高度安全设备的要求。

要求

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

另请参阅

NCryptBuffer