InitializeEnclave function

Initializes an enclave that you created and loaded with data.

Syntax


BOOL WINAPI InitializeEnclave(
  _In_ HANDLE  hProcess,
  _In_ LPVOID  lpAddress,
  _In_ LPVOID  lpEnclaveInformation,
  _In_ DWORD   dwInfoLength,
  _In_ LPDWORD lpEnclaveError
);

Parameters

hProcess [in]

A handle to the process for which the enclave was created.

lpAddress [in]

Any address within the enclave.

lpEnclaveInformation [in]

A pointer to architecture-specific information to use to initialize the enclave. For the ENCLAVE_TYPE_SGX enclave type, specify a pointer to an ENCLAVE_INIT_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 [in]

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 contains the error that the EINIT instruction generated if the function fails and .GetLastError returns ERROR_ENCLAVE_FAILURE.

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. 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

An 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, the EINIT instruction that the ENCLAVE_INIT_INFO_SGX structure specified generated an error. The value of the lpEnclaveError parameter contains the error that the instruction generated.

ERROR_BAD_LENGTH

The value of the dwInfoLength parameter did not match the value expected based on the value specified for the lpEnclaveInformation parameter.

ERROR_RETRY

The processor was not able to initialize the enclave in a timely fashion. Try to initialize the enclave again.

 

Remarks

To create an enclave, use the CreateEnclave function. To load data into the enclave before you initialize it, use the LoadEnclaveData function.

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.

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

CreateEnclave
LoadEnclaveData
VirtualFree
VirtualFreeEx
ENCLAVE_INIT_INFO_SGX

 

 

Show: