Windows apps
Collapse the table of content
Expand the table of content
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

CreateEnclave function

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


PVOID WINAPI CreateEnclave(
  _In_      HANDLE  hProcess,
  _In_opt_  LPVOID  lpAddress,
  _In_      SIZE_T  dwSize,
  _In_      SIZE_T  dwInitialCommittment,
  _In_      DWORD   flEnclaveType,
  _In_      LPCVOID lpEnclaveInformation,
  _In_      DWORD   dwInfoLength,
  _Out_opt_ LPDWORD lpEnclaveError
);

Parameters

hProcess [in]

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

lpAddress [in, optional]

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

dwSize [in]

The size of the enclave that you want to create, in bytes.

dwInitialCommittment [in]

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.

flEnclaveType [in]

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

Only a value of ENCLAVE_TYPE_SGX is currently supported, which specifies an enclave for the Intel Software Guard Extensions (SGX) architecture extension.

lpEnclaveInformation [in]

A pointer to the architecture-specific information to use to create the enclave. For the ENCLAVE_TYPE_SGX enclave type, you must specify a pointer to an ENCLAVE_CREATE_INFO_SGX structure.

dwInfoLength [in]

The length of the structure that the lpEnclaveInformation parameter points to, in bytes. For the ENCLAVE_TYPE_SGX enclave type, this value must be 4096.

lpEnclaveError [out, optional]

An optional pointer to a variable that receives an enclave error code that is architecture-specific. For the ENCLAVE_TYPE_SGX enclave type, 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 codeDescription
ERROR_ENCLAVE_FAILURE

A failure specific to the underlying enclave architecture occurred. The value for the lpEnclaveError parameter contains the architecture-specific error.

For the ENCLAVE_TYPE_SGX enclave type, this value is not used for this function.

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.

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

Minimum supported client

Windows 10 [desktop apps only]

Minimum supported server

Windows Server 2016 [desktop apps only]

Header

Enclaveapi.h (include Winbase.h)

Library

Kernel32.lib

DLL

Api-ms-win-core-enclave-l1-1-0;
Kernel32.dll;
KernelBase.dll

See also

IsEnclaveTypeSupported
LoadEnclaveData
InitializeEnclave
VirtualFree
VirtualFreeEx
ENCLAVE_CREATE_INFO_SGX

 

 

Show:
© 2017 Microsoft