Funzione CreateEnclave (enclaveapi.h)

Articolo
02/03/2024

Crea una nuova enclave non inizializzata. Un'enclave è un'area isolata di codice e dati all'interno dello spazio indirizzi per un'applicazione. Solo il codice eseguito all'interno dell'enclave può accedere ai dati all'interno della stessa enclave.

Sintassi

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

Parametri

[in] hProcess

Handle per il processo per il quale si vuole creare un'enclave.

[in, optional] lpAddress

Indirizzo di base preferito dell'enclave. Specificare NULL per fare in modo che il sistema operativo assegni l'indirizzo di base.

[in] dwSize

Dimensioni dell'enclave che si vuole creare, incluse le dimensioni del codice che verrà caricato nell'enclave, in byte.

Le enclave VBS devono avere dimensioni multiple di 2 MB.

Le enclave SGX devono avere una potenza di 2 dimensioni e devono avere la base allineata alla stessa potenza di 2 delle dimensioni, con un allineamento minimo di 2 MB. Ad esempio, se l'enclave è di 128 MB, la base deve essere allineata a un limite di 128 MB.

[in] dwInitialCommitment

Quantità di memoria di cui eseguire il commit per l'enclave, in byte.

Se la quantità di memoria dell'enclave disponibile non è sufficiente per eseguire il commit di questo numero di byte, la creazione dell'enclave ha esito negativo. Qualsiasi memoria che rimane inutilizzata quando si inizializza l'enclave chiamando InitializeEnclave viene restituita all'elenco di pagine gratuite.

Il valore del parametro dwInitialCommittment non deve superare il valore del parametro dwSize .

Questo parametro non viene usato per le enclave di sicurezza basata su virtualizzazione.

[in] flEnclaveType

Tipo di architettura dell'enclave che si vuole creare. Per verificare che sia supportato un tipo di enclave, chiamare IsEnclaveTypeSupported.

Valore	Significato
ENCLAVE_TYPE_SGX `0x00000001`	Enclave per l'estensione dell'architettura Intel Software Guard Extensions (SGX).
ENCLAVE_TYPE_SGX2 `0x00000002`	Supporta enclave SGX2 e SGX1. La piattaforma e il sistema operativo supportano le istruzioni SGX2 con EDMM su questa piattaforma (oltre ad altri costrutti SGX2).
ENCLAVE_TYPE_VBS `0x00000010`	Enclave VBS.

[in] lpEnclaveInformation

Puntatore alle informazioni specifiche dell'architettura da usare per creare l'enclave.

Per i tipi di enclave ENCLAVE_TYPE_SGX e ENCLAVE_TYPE_SGX2 , è necessario specificare un puntatore a una struttura ENCLAVE_CREATE_INFO_SGX .

Per il tipo di enclave ENCLAVE_TYPE_VBS , è necessario specificare un puntatore a una struttura ENCLAVE_CREATE_INFO_VBS .

[in] dwInfoLength

Lunghezza della struttura a cui punta il parametro lpEnclaveInformation , in byte. Per i tipi di enclave ENCLAVE_TYPE_SGX e ENCLAVE_TYPE_SGX2 , questo valore deve essere 4096. Per il tipo di enclave ENCLAVE_TYPE_VBS , questo valore deve essere sizeof(ENCLAVE_CREATE_INFO_VBS), ovvero 36 byte.

[out, optional] lpEnclaveError

Puntatore facoltativo a una variabile che riceve un codice di errore dell'enclave specifico dell'architettura. Per i tipi dienclave ENCLAVE_TYPE_SGX, ENCLAVE_TYPE_SGX2 e ENCLAVE_TYPE_VBS , il parametro lpEnclaveError non viene usato.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è l'indirizzo di base dell'enclave creato.

Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Per un elenco dei codici di errore comuni, vedere Codici di errore di sistema. Per questa funzione si applicano anche i codici di errore seguenti.

Codice restituito	Descrizione
ERROR_NOT_SUPPORTED	È stato specificato un tipo di enclave non supportato.
ERROR_BAD_LENGTH	Il valore del parametro dwInfoLength non corrisponde al valore previsto in base al valore specificato per il parametro lpEnclaveInformation .

Commenti

Per caricare i dati in un'enclave dopo averlo creato, chiamare LoadEnclaveData. Per inizializzare l'enclave dopo aver caricato i dati, chiamare InitializeEnclave.

Windows 10 versione 1709: per eliminare l'enclave al termine dell'uso, chiamare DeleteEnclave. Non è possibile eliminare un enclave VBS chiamando la funzione VirtualFree o VirtualFreeEx . È comunque possibile eliminare un enclave SGX chiamando VirtualFree o VirtualFreeEx.

Windows 10, versione 1507, Windows 10, versione 1511, Windows 10, versione 1607 e Windows 10, versione 1703: per eliminare l'enclave al termine dell'uso, chiamare la funzione VirtualFree o VirtualFreeEx e specificare i valori seguenti:

Indirizzo di base dell'enclave per il parametro lpAddress .
0 per il parametro dwSize .
MEM_RELEASE per il parametro dwFreeType . Il valore MEM_DECOMMIT non è supportato per le enclave.

Per informazioni sull'estensione dell'architettura Intel Software Guard Extensions (SGX), vedere Intel Software Guard Extensions(Estensioni Intel Software Guard).

Requisiti

Requisito	Valore
Client minimo supportato	Windows 10 [app desktop \| App UWP]
Server minimo supportato	Windows Server 2016 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	enclaveapi.h (include Winbase.h)
Libreria	Kernel32.lib
DLL	Api-ms-win-core-enclave-l1-1-0.dll; Kernel32.dll; KernelBase.dll