通过

NCryptCreatePersistedKey 函数 (ncrypt.h)

  • 项目

NCryptCreatePersistedKey 函数创建一个新密钥，并将其存储在指定的密钥存储提供程序中。 使用此函数创建密钥后，可以使用 NCryptSetProperty 函数设置其属性;但是，在调用 NCryptFinalizeKey 函数之前，无法使用密钥。

语法

SECURITY_STATUS NCryptCreatePersistedKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           LPCWSTR            pszAlgId,
  [in, optional] LPCWSTR            pszKeyName,
  [in]           DWORD              dwLegacyKeySpec,
  [in]           DWORD              dwFlags
);

参数

[in] hProvider

要创建密钥的密钥存储提供程序的句柄。 此句柄是使用 NCryptOpenStorageProvider 函数获取的。

[out] phKey

接收密钥句柄 的NCRYPT_KEY_HANDLE 变量的地址。 完成使用此句柄后，通过将其传递给 NCryptFreeObject 函数来释放它。 若要删除磁盘上的密钥文件，请将句柄传递给 NCryptDeleteKey 函数。 这也会释放句柄。 因此，应用程序可以将句柄传递给 NCryptFreeObject 或 NCryptDeleteKey，但不能同时传递两者。

[in] pszAlgId

指向以 null 结尾的 Unicode 字符串的指针，该字符串包含用于创建密钥的加密算法的标识符。 这可以是标准 CNG 算法标识符 之一，也可以是另一个已注册算法的标识符。

[in, optional] pszKeyName

指向包含密钥名称的以 null 结尾的 Unicode 字符串的指针。 如果此参数为 NULL，则此函数将创建一个不持久保存的临时密钥。

[in] dwLegacyKeySpec

指定密钥类型的旧标识符。 这可以是以下值之一：

值 含义
AT_KEYEXCHANGE 密钥是密钥交换密钥。
AT_SIGNATURE 密钥是签名密钥。
0 键不是上述类型。

[in] dwFlags

一组标志，用于修改此函数的行为。 这可以是零，也可以是以下一个或多个值的组合：

值 含义
NCRYPT_MACHINE_KEY_FLAG 密钥适用于本地计算机。 如果此标志不存在，则密钥将应用于当前用户。
NCRYPT_OVERWRITE_KEY_FLAG 如果容器中已存在具有指定名称的密钥，则会覆盖现有密钥。 如果未指定此标志，并且已存在具有指定名称的键，则此函数将返回 NTE_EXISTS。
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 不可用。

注解

重要

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

如果要创建 RSA 密钥对，还可以将密钥存储在旧存储中，以便在密钥完成时将 NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG 标志传递给 NCryptFinalizeKey 函数，以便将其与 CryptoAPI 一起使用。

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

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

另请参阅

NCryptDeleteKey

NCryptFinalizeKey

NCryptImportKey