CreateEnclave function (enclaveapi.h)

Article
02/02/2024

Creates a new uninitialized enclave. An enclave is an isolated region of code and data within the address space for an application. Only code that runs within the enclave can access data within the same enclave.

Syntax

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
);

Parameters

[in] hProcess

A handle to the process for which you want to create an enclave.

[in, optional] lpAddress

The preferred base address of the enclave. Specify NULL to have the operating system assign the base address.

[in] dwSize

The size of the enclave that you want to create, including the size of the code that you will load into the enclave, in bytes.

VBS enclaves must be a multiple of 2 MB in size.

SGX enclaves must be a power of 2 in size and must have their base aligned to the same power of 2 as the size, with a minimum alignment of 2 MB. As an example, if the enclave is 128 MB, then its base must be aligned to a 128 MB boundary.

[in] dwInitialCommitment

The amount of memory to commit for the enclave, in bytes.

If the amount of enclave memory available is not sufficient to commit this number of bytes, enclave creation fails. Any memory that remains unused when you initialize the enclave by calling InitializeEnclave is returned to the list of free pages.

The value of the dwInitialCommittment parameter must not exceed the value of the dwSize parameter.

This parameter is not used for virtualization-based security (VBS) enclaves.

[in] flEnclaveType

The architecture type of the enclave that you want to create. To verify that an enclave type is supported, call IsEnclaveTypeSupported.

Value	Meaning
ENCLAVE_TYPE_SGX `0x00000001`	An enclave for the Intel Software Guard Extensions (SGX) architecture extension.
ENCLAVE_TYPE_SGX2 `0x00000002`	Supports SGX2 and SGX1 enclaves. The platform and OS support SGX2 instructions with EDMM on this platform (in addition to other SGX2 constructs).
ENCLAVE_TYPE_VBS `0x00000010`	A VBS enclave.

[in] lpEnclaveInformation

A pointer to the architecture-specific information to use to create the enclave.

For the ENCLAVE_TYPE_SGX and ENCLAVE_TYPE_SGX2 enclave types, you must specify a pointer to an ENCLAVE_CREATE_INFO_SGX structure.

For the ENCLAVE_TYPE_VBS enclave type, you must specify a pointer to an ENCLAVE_CREATE_INFO_VBS structure.

[in] dwInfoLength

The length of the structure that the lpEnclaveInformation parameter points to, in bytes. For the ENCLAVE_TYPE_SGX and ENCLAVE_TYPE_SGX2 enclave types, this value must be 4096. For the ENCLAVE_TYPE_VBS enclave type, this value must be sizeof(ENCLAVE_CREATE_INFO_VBS), which is 36 bytes.

[out, optional] lpEnclaveError

An optional pointer to a variable that receives an enclave error code that is architecture-specific. For the ENCLAVE_TYPE_SGX, ENCLAVE_TYPE_SGX2 and ENCLAVE_TYPE_VBS enclave types, the lpEnclaveError parameter is not used.

Return value

If the function succeeds, the return value is the base address of the created enclave.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

For a list of common error codes, see System Error Codes. The following error codes also apply for this function.

Return code	Description
ERROR_NOT_SUPPORTED	An unsupported enclave type was specified.
ERROR_BAD_LENGTH	The value of the dwInfoLength parameter did not match the value expected based on the value specified for the lpEnclaveInformation parameter.

Remarks

To load data into an enclave after you create it, call LoadEnclaveData. To initialize the enclave after you load the data, call InitializeEnclave.

Windows 10, version 1709: To delete the enclave when you finish using it, call DeleteEnclave. You cannot delete a VBS enclave by calling the VirtualFree or VirtualFreeEx function. You can still delete an SGX enclave by calling VirtualFree or VirtualFreeEx.

Windows 10, version 1507, Windows 10, version 1511, Windows 10, version 1607 and Windows 10, version 1703: To delete the enclave when you finish using it, call the VirtualFree or VirtualFreeEx function and specify the following values:

The base address of the enclave for the lpAddress parameter.
0 for the dwSize parameter.
MEM_RELEASE for the dwFreeType parameter. The MEM_DECOMMIT value is not supported for enclaves.

For information about the Intel Software Guard Extensions (SGX) architecture extension, see Intel Software Guard Extensions.

Requirements

Requirement	Value
Minimum supported client	Windows 10 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2016 [desktop apps \| UWP apps]
Target Platform	Windows
Header	enclaveapi.h (include Winbase.h)
Library	Kernel32.lib
DLL	Api-ms-win-core-enclave-l1-1-0.dll; Kernel32.dll; KernelBase.dll