CreateEnclave 函式 (enclaveapi.h)

發行項
02/29/2024

建立新的未初始化記憶體保護區。記憶體保護區是應用程式位址空間內程式代碼和數據隔離的區域。只有記憶體保護區內執行的程式代碼可以存取相同記憶體保護區內的數據。

語法

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

您要為其建立記憶體保護區之進程的句柄。

[in, optional] lpAddress

記憶體保護區的慣用基位址。指定 NULL 以讓作業系統指派基位址。

[in] dwSize

您想要建立的記憶體保護區大小，包括您將載入記憶體保護區的程式代碼大小，以位元組為單位。

VBS 記憶體保護區的大小必須是 2 MB 的倍數。

SGX 記憶體保護區必須是大小為 2 的電源，且其基底必須對齊大小相同的 2，且最小對齊方式為 2 MB。例如，如果記憶體保護區為 128 MB，則其基底必須對齊 128 MB 界限。

[in] dwInitialCommitment

要為記憶體保護區認可的記憶體數量，以位元組為單位。

如果可用的記憶體數量不足以認可這個位元組數目，記憶體保護區建立就會失敗。當您呼叫 InitializeEnclave 來初始化記憶體保護區時，任何仍未使用的記憶體都會傳回至可用頁面清單。

dwInitialCommittment 參數的值不得超過 dwSize 參數的值。

此參數不會用於虛擬式安全性 (VBS) 記憶體保護區。

[in] flEnclaveType

您要建立之內存保護區的架構類型。若要確認支援記憶體保護區類型，請呼叫 IsEnclaveTypeSupported。

值	意義
ENCLAVE_TYPE_SGX `0x00000001`	Intel Software Guard Extensions (SGX) 架構延伸模組的記憶體保護區。
ENCLAVE_TYPE_SGX2 `0x00000002`	支援SGX2和SGX1記憶體保護區。除了其他 SGX2 建構) 之外，平臺和 OS 在此平臺上也支援 EDMM 的 SGX2 指示 (。
ENCLAVE_TYPE_VBS `0x00000010`	VBS 記憶體保護區。

[in] lpEnclaveInformation

用來建立記憶體保護區之架構特定資訊的指標。

針對 ENCLAVE_TYPE_SGX 和 ENCLAVE_TYPE_SGX2 記憶體保護區類型，您必須指定 ENCLAVE_CREATE_INFO_SGX 結構的指標。

針對 ENCLAVE_TYPE_VBS 記憶體保護區類型，您必須指定 ENCLAVE_CREATE_INFO_VBS 結構的指標。

[in] dwInfoLength

lpEnclaveInformation 參數指向的結構長度，以位元組為單位。對於 ENCLAVE_TYPE_SGX 和 ENCLAVE_TYPE_SGX2 記憶體保護區類型，此值必須是 4096。對於 ENCLAVE_TYPE_VBS 記憶體保護區類型，此值必須是 sizeof(ENCLAVE_CREATE_INFO_VBS)，也就是 36 個字節。

[out, optional] lpEnclaveError

可接收架構特定記憶體保護區錯誤碼之變數的選擇性指標。針對 ENCLAVE_TYPE_SGX、 ENCLAVE_TYPE_SGX2 和 ENCLAVE_TYPE_VBS 記憶體保護區類型，不會使用 lpEnclaveError 參數。

傳回值

如果函式成功，則傳回值是所建立記憶體保護區的基位址。

如果函式失敗，傳回值為 NULL。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

如需常見錯誤碼的清單，請參閱系統錯誤碼。下列錯誤碼也適用於此函式。

傳回碼	Description
ERROR_NOT_SUPPORTED	已指定不支援的記憶體保護區類型。
ERROR_BAD_LENGTH	dwInfoLength 參數的值不符合根據為 lpEnclaveInformation 參數指定的值所預期的值。

備註

若要在建立數據後將數據載入記憶體保護區，請呼叫 LoadEnclaveData。若要在載入數據之後初始化記憶體保護區，請呼叫 InitializeEnclave。

Windows 10 版本 1709：若要在完成使用記憶體保護區時刪除記憶體保護區，請呼叫 DeleteEnclave。您無法藉由呼叫 VirtualFree 或 VirtualFreeEx 函式來刪除 VBS 記憶體保護區。您仍然可以呼叫 VirtualFree 或 VirtualFreeEx 來刪除 SGX 記憶體保護區。

Windows 10 版本 1507、Windows 10 版本 1511、Windows 10 版本 1607 和 Windows 10 版本 1703：若要在完成使用記憶體保護區時刪除記憶體保護區，請呼叫 VirtualFree 或 VirtualFreeEx 函式並指定下列值：

lpAddress 參數記憶體保護區的基位址。
0 表示 dwSize 參數。
dwFreeType 參數MEM_RELEASE。記憶體保護區不支援 MEM_DECOMMIT 值。

如需 Intel Software Guard Extensions (SGX) 架構延伸模組的相關信息，請參閱 Intel Software Guard 擴充功能。

規格需求

需求	值
最低支援的用戶端	Windows 10 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2016 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	enclaveapi.h (包含 Winbase.h)
程式庫	Kernel32.lib
DLL	Api-ms-win-core-enclave-l1-1-0.dll;Kernel32.dll;KernelBase.dll