createEnclave 函数 (enclaveapi.h)

项目
02/03/2024

创建新的未初始化 enclave。 enclave 是应用程序地址空间内代码和数据的独立区域。只有 enclave 中运行的代码才能访问同一 enclave 中的数据。

语法

LPVOID CreateEnclave(
  [in]            HANDLE  hProcess,
  [in, optional]  LPVOID  lpAddress,
  [in]            SIZE_T  dwSize,
  [in]            SIZE_T  dwInitialCommitment,
  [in]            DWORD   flEnclaveType,
  [in]            LPCVOID lpEnclaveInformation,
  [in]            DWORD   dwInfoLength,
  [out, optional] LPDWORD lpEnclaveError
);

参数

[in] hProcess

要为其创建 enclave 的进程句柄。

[in, optional] lpAddress

enclave 的首选基址。指定 NULL 可让操作系统分配基址。

[in] dwSize

要创建的 enclave 的大小，包括要加载到 enclave 中的代码的大小（以字节为单位）。

VBS enclave 的大小必须是 2 MB 的倍数。

SGX enclave 的大小必须为 2 的幂，并且其底数必须与大小相同的 2 次幂对齐，最小对齐方式为 2 MB。例如，如果 enclave 为 128 MB，则其基数必须与 128 MB 边界对齐。

[in] dwInitialCommitment

要为 enclave 提交的内存量（以字节为单位）。

如果可用 enclave 内存量不足以提交此字节数，则 enclave 创建将失败。通过调用 InitializeEnclave 初始化 enclave 时保持未使用的任何内存将返回到可用页列表。

dwInitialCommittment 参数的值不得超过 dwSize 参数的值。

此参数不用于基于虚拟化的安全 (VBS) enclave。

[in] flEnclaveType

要创建的 enclave 的体系结构类型。若要验证 enclave 类型是否受支持，请调用 IsEnclaveTypeSupported。

值	含义
ENCLAVE_TYPE_SGX `0x00000001`	Intel Software Guard Extensions (SGX) 体系结构扩展的 enclave。
ENCLAVE_TYPE_SGX2 `0x00000002`	支持 SGX2 和 SGX1 enclave。除了其他 SGX2 构造) 之外，平台和 OS 支持此平台上的 EDMM 的 SGX2 指令 (。
ENCLAVE_TYPE_VBS `0x00000010`	VBS enclave。

[in] lpEnclaveInformation

指向用于创建 enclave 的特定于体系结构的信息的指针。

对于 ENCLAVE_TYPE_SGX 和 ENCLAVE_TYPE_SGX2 enclave 类型，必须指定指向 ENCLAVE_CREATE_INFO_SGX 结构的指针。

对于 ENCLAVE_TYPE_VBS enclave 类型，必须指定指向 ENCLAVE_CREATE_INFO_VBS 结构的指针。

[in] dwInfoLength

lpEnclaveInformation 参数指向的结构的长度（以字节为单位）。对于 ENCLAVE_TYPE_SGX 和 ENCLAVE_TYPE_SGX2 enclave 类型，此值必须为 4096。对于 ENCLAVE_TYPE_VBS enclave 类型，此值必须为 sizeof(ENCLAVE_CREATE_INFO_VBS)，即 36 字节。

[out, optional] lpEnclaveError

指向接收特定于体系结构的 enclave 错误代码的变量的可选指针。对于 ENCLAVE_TYPE_SGX、 ENCLAVE_TYPE_SGX2 和 ENCLAVE_TYPE_VBS enclave 类型，不使用 lpEnclaveError 参数。

返回值

如果函数成功，则返回值为所创建的 enclave 的基址。

如果函数失败，则返回值为 NULL。要获得更多的错误信息，请调用 GetLastError。

有关常见错误代码的列表，请参阅系统错误代码。以下错误代码也适用于此函数。

返回代码	说明
ERROR_NOT_SUPPORTED	指定了不受支持的 enclave 类型。
ERROR_BAD_LENGTH	dwInfoLength 参数的值与基于为 lpEnclaveInformation 参数指定的值的预期值不匹配。

注解

若要在创建 enclave 后将数据加载到 enclave 中，请调用 LoadEnclaveData。若要在加载数据后初始化 enclave，请调用 InitializeEnclave。

Windows 10版本 1709：若要在使用完 enclave 后将其删除，请调用 DeleteEnclave。无法通过调用 VirtualFree 或 VirtualFreeEx 函数删除 VBS enclave。仍可通过调用 VirtualFree 或 VirtualFreeEx 删除 SGX enclave。

Windows 10版本 1507、Windows 10、版本 1511、Windows 10、版本 1607 和 Windows 10 版本 1703：若要在使用完 enclave 后删除它，请调用 VirtualFree 或 VirtualFreeEx 函数并指定以下值：

lpAddress 参数的 enclave 基址。
0 表示 dwSize 参数。
dwFreeType 参数的MEM_RELEASE。 enclave 不支持 MEM_DECOMMIT 值。

有关 Intel Software Guard Extensions (SGX) 体系结构扩展的信息，请参阅 Intel Software Guard Extensions。

要求

要求	值
最低受支持的客户端	Windows 10 [桌面应用 \|UWP 应用]
最低受支持的服务器	Windows Server 2016 [桌面应用 \|UWP 应用]
目标平台	Windows
标头	enclaveapi.h (包括 Winbase.h)
Library	Kernel32.lib
DLL	Api-ms-win-core-enclave-l1-1-0.dll;Kernel32.dll;KernelBase.dll