Função CreateEnclave (enclaveapi.h)

Artigo
02/02/2024

Cria um novo enclave não inicializado. Um enclave é uma região isolada de código e dados dentro do espaço de endereço de um aplicativo. Somente o código executado dentro do enclave pode acessar dados no mesmo enclave.

Sintaxe

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

Um identificador para o processo para o qual você deseja criar um enclave.

[in, optional] lpAddress

O endereço base preferencial do enclave. Especifique NULL para que o sistema operacional atribua o endereço base.

[in] dwSize

O tamanho do enclave que você deseja criar, incluindo o tamanho do código que você carregará no enclave, em bytes.

Os enclaves de VBS devem ter um múltiplo de 2 MB de tamanho.

Os enclaves SGX devem ter uma potência de 2 em tamanho e devem ter sua base alinhada à mesma potência de 2 que o tamanho, com um alinhamento mínimo de 2 MB. Por exemplo, se o enclave for de 128 MB, sua base deverá ser alinhada a um limite de 128 MB.

[in] dwInitialCommitment

A quantidade de memória a ser confirmada para o enclave, em bytes.

Se a quantidade de memória de enclave disponível não for suficiente para confirmar esse número de bytes, a criação do enclave falhará. Qualquer memória que permanece não usada quando você inicializa o enclave chamando InitializeEnclave é retornada para a lista de páginas gratuitas.

O valor do parâmetro dwInitialCommittment não deve exceder o valor do parâmetro dwSize .

Esse parâmetro não é usado para enclaves de VBS (segurança baseada em virtualização).

[in] flEnclaveType

O tipo de arquitetura do enclave que você deseja criar. Para verificar se há suporte para um tipo de enclave, chame IsEnclaveTypeSupported.

Valor	Significado
ENCLAVE_TYPE_SGX `0x00000001`	Um enclave para a extensão de arquitetura SGX (Extensões do Intel Software Guard).
ENCLAVE_TYPE_SGX2 `0x00000002`	Dá suporte a enclaves SGX2 e SGX1. A plataforma e o sistema operacional dão suporte a instruções SGX2 com o EDMM nesta plataforma (além de outros constructos SGX2).
ENCLAVE_TYPE_VBS `0x00000010`	Um enclave de VBS.

[in] lpEnclaveInformation

Um ponteiro para as informações específicas da arquitetura a serem usadas para criar o enclave.

Para os tipos de enclave ENCLAVE_TYPE_SGX e ENCLAVE_TYPE_SGX2 , você deve especificar um ponteiro para uma estrutura de ENCLAVE_CREATE_INFO_SGX .

Para o tipo de enclave ENCLAVE_TYPE_VBS , você deve especificar um ponteiro para uma estrutura ENCLAVE_CREATE_INFO_VBS .

[in] dwInfoLength

O comprimento da estrutura para a qual o parâmetro lpEnclaveInformation aponta, em bytes. Para os tipos de enclave ENCLAVE_TYPE_SGX e ENCLAVE_TYPE_SGX2 , esse valor deve ser 4096. Para o tipo de enclave ENCLAVE_TYPE_VBS , esse valor deve ser sizeof(ENCLAVE_CREATE_INFO_VBS), que é de 36 bytes.

[out, optional] lpEnclaveError

Um ponteiro opcional para uma variável que recebe um código de erro de enclave específico da arquitetura. Para os tipos de enclave ENCLAVE_TYPE_SGX, ENCLAVE_TYPE_SGX2 e ENCLAVE_TYPE_VBS , o parâmetro lpEnclaveError não é usado.

Retornar valor

Se a função for bem-sucedida, o valor retornado será o endereço base do enclave criado.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Para obter uma lista de códigos de erro comuns, consulte Códigos de erro do sistema. Os códigos de erro a seguir também se aplicam a essa função.

Código de retorno	Descrição
ERROR_NOT_SUPPORTED	Um tipo de enclave sem suporte foi especificado.
ERROR_BAD_LENGTH	O valor do parâmetro dwInfoLength não correspondeu ao valor esperado com base no valor especificado para o parâmetro lpEnclaveInformation .

Comentários

Para carregar dados em um enclave depois de criá-los, chame LoadEnclaveData. Para inicializar o enclave depois de carregar os dados, chame InitializeEnclave.

Windows 10, versão 1709: para excluir o enclave quando terminar de usá-lo, chame DeleteEnclave. Não é possível excluir um enclave de VBS chamando a função VirtualFree ou VirtualFreeEx . Você ainda pode excluir um enclave SGX chamando VirtualFree ou VirtualFreeEx.

Windows 10, versão 1507, Windows 10, versão 1511, Windows 10, versão 1607 e Windows 10, versão 1703: para excluir o enclave quando terminar de usá-lo, chame a função VirtualFree ou VirtualFreeEx e especifique os seguintes valores:

O endereço base do enclave para o parâmetro lpAddress .
0 para o parâmetro dwSize .
MEM_RELEASE para o parâmetro dwFreeType . Não há suporte para o valor de MEM_DECOMMIT para enclaves.

Para obter informações sobre a extensão de arquitetura SGX (Extensões do Intel Software Guard), consulte Extensões do Intel Software Guard.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 10 [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2016 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	enclaveapi.h (inclua Winbase.h)
Biblioteca	Kernel32.lib
DLL	Api-ms-win-core-enclave-l1-1-0.dll; Kernel32.dll; KernelBase.dll