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 不可用，操作将生成软件隔离的密钥。 (*请参阅备注) |
| NCRYPT_USE_PER_BOOT_KEY_FLAG | 可与 NCRYPT_REQUIRE_VBS_FLAG 或 NCRYPT_PREFER_VBS_FLAG一起使用的其他标志。 指示基于虚拟化的安全 (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 |