Función CreateEnclave (enclaveapi.h)

Artículo
02/06/2024

Crea un nuevo enclave sin inicializar. Un enclave es una región aislada de código y datos dentro del espacio de direcciones de una aplicación. Solo el código que se ejecuta dentro del enclave puede acceder a los datos dentro del mismo enclave.

Sintaxis

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

Parámetros

[in] hProcess

Identificador del proceso para el que desea crear un enclave.

[in, optional] lpAddress

Dirección base preferida del enclave. Especifique NULL para que el sistema operativo asigne la dirección base.

[in] dwSize

Tamaño del enclave que desea crear, incluido el tamaño del código que se cargará en el enclave, en bytes.

Los enclaves de VBS deben tener un tamaño de múltiplo de 2 MB.

Los enclaves SGX deben ser una potencia de 2 en tamaño y deben tener su base alineada con la misma potencia de 2 que el tamaño, con una alineación mínima de 2 MB. Por ejemplo, si el enclave es de 128 MB, su base debe estar alineada con un límite de 128 MB.

[in] dwInitialCommitment

Cantidad de memoria que se va a confirmar para el enclave, en bytes.

Si la cantidad de memoria del enclave disponible no es suficiente para confirmar este número de bytes, se produce un error en la creación del enclave. Cualquier memoria que permanezca sin usar al inicializar el enclave llamando a InitializeEnclave se devuelve a la lista de páginas gratuitas.

El valor del parámetro dwInitialCommittment no debe superar el valor del parámetro dwSize .

Este parámetro no se usa para enclaves de seguridad basados en virtualización (VBS).

[in] flEnclaveType

Tipo de arquitectura del enclave que desea crear. Para comprobar que se admite un tipo de enclave, llame a IsEnclaveTypeSupported.

Valor	Significado
ENCLAVE_TYPE_SGX `0x00000001`	Un enclave para la extensión de arquitectura Intel Software Guard Extensions (SGX).
ENCLAVE_TYPE_SGX2 `0x00000002`	Admite enclaves SGX2 y SGX1. La plataforma y el sistema operativo admiten instrucciones SGX2 con EDMM en esta plataforma (además de otras construcciones SGX2).
ENCLAVE_TYPE_VBS `0x00000010`	Un enclave de VBS.

[in] lpEnclaveInformation

Puntero a la información específica de la arquitectura que se va a usar para crear el enclave.

Para los tipos de enclave de ENCLAVE_TYPE_SGX y ENCLAVE_TYPE_SGX2 , debe especificar un puntero a una estructura de ENCLAVE_CREATE_INFO_SGX .

Para el tipo de enclave de ENCLAVE_TYPE_VBS , debe especificar un puntero a una estructura de ENCLAVE_CREATE_INFO_VBS .

[in] dwInfoLength

Longitud de la estructura a la que apunta el parámetro lpEnclaveInformation , en bytes. Para los tipos de enclave ENCLAVE_TYPE_SGX y ENCLAVE_TYPE_SGX2 , este valor debe ser 4096. Para el tipo de enclave de ENCLAVE_TYPE_VBS , este valor debe ser sizeof(ENCLAVE_CREATE_INFO_VBS), que es de 36 bytes.

[out, optional] lpEnclaveError

Puntero opcional a una variable que recibe un código de error de enclave específico de la arquitectura. Para los tipos de enclave de ENCLAVE_TYPE_SGX, ENCLAVE_TYPE_SGX2 y ENCLAVE_TYPE_VBS , no se usa el parámetro lpEnclaveError .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es la dirección base del enclave creado.

Si la función no se realiza correctamente, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Para obtener una lista de códigos de error comunes, consulte Códigos de error del sistema. Los siguientes códigos de error también se aplican a esta función.

Código devuelto	Descripción
ERROR_NOT_SUPPORTED	Se especificó un tipo de enclave no admitido.
ERROR_BAD_LENGTH	El valor del parámetro dwInfoLength no coincide con el valor esperado en función del valor especificado para el parámetro lpEnclaveInformation .

Comentarios

Para cargar datos en un enclave después de crearlos, llame a LoadEnclaveData. Para inicializar el enclave después de cargar los datos, llame a InitializeEnclave.

Windows 10, versión 1709: para eliminar el enclave cuando termine de usarlo, llame a DeleteEnclave. No se puede eliminar un enclave de VBS llamando a la función VirtualFree o VirtualFreeEx . Todavía puede eliminar un enclave SGX llamando a VirtualFree o VirtualFreeEx.

Windows 10, versión 1507, Windows 10, versión 1511, Windows 10, versión 1607 y Windows 10, versión 1703: para eliminar el enclave cuando termine de usarlo, llame a la función VirtualFree o VirtualFreeEx y especifique los valores siguientes:

Dirección base del enclave para el parámetro lpAddress .
0 para el parámetro dwSize .
MEM_RELEASE para el parámetro dwFreeType . El valor de MEM_DECOMMIT no se admite para enclaves.

Para obtener información sobre la extensión de arquitectura Intel Software Guard Extensions (SGX), vea Intel Software Guard Extensions.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 10 [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2016 [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	enclaveapi.h (incluya Winbase.h)
Library	Kernel32.lib
Archivo DLL	Api-ms-win-core-enclave-l1-1-0.dll; Kernel32.dll; KernelBase.dll