CreateEnclave, fonction (enclaveapi.h)

Article
02/02/2024

Crée une enclave non initialisée. Une enclave est une région isolée de code et de données dans l’espace d’adressage d’une application. Seul le code qui s’exécute dans l’enclave peut accéder aux données dans la même enclave.

Syntaxe

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

Paramètres

[in] hProcess

Handle du processus pour lequel vous souhaitez créer une enclave.

[in, optional] lpAddress

Adresse de base préférée de l’enclave. Spécifiez NULL pour que le système d’exploitation attribue l’adresse de base.

[in] dwSize

Taille de l’enclave que vous souhaitez créer, y compris la taille du code que vous allez charger dans l’enclave, en octets.

Les enclaves VBS doivent avoir une taille multiple de 2 Mo.

Les enclaves SGX doivent avoir une puissance de 2 et avoir leur base alignée sur la même puissance de 2 que la taille, avec un alignement minimal de 2 Mo. Par exemple, si l’enclave est de 128 Mo, sa base doit être alignée sur une limite de 128 Mo.

[in] dwInitialCommitment

Quantité de mémoire à valider pour l’enclave, en octets.

Si la quantité de mémoire d’enclave disponible n’est pas suffisante pour valider ce nombre d’octets, la création de l’enclave échoue. Toute mémoire qui reste inutilisée lorsque vous initialisez l’enclave en appelant InitializeEnclave est retournée à la liste des pages libres.

La valeur du paramètre dwInitialCommittment ne doit pas dépasser la valeur du paramètre dwSize .

Ce paramètre n’est pas utilisé pour les enclaves de sécurité basées sur la virtualisation (VBS).

[in] flEnclaveType

Type d’architecture de l’enclave que vous souhaitez créer. Pour vérifier qu’un type d’enclave est pris en charge, appelez IsEnclaveTypeSupported.

Valeur	Signification
ENCLAVE_TYPE_SGX `0x00000001`	Enclave pour l’extension d’architecture Intel Software Guard Extensions (SGX).
ENCLAVE_TYPE_SGX2 `0x00000002`	Prend en charge les enclaves SGX2 et SGX1. La plateforme et le système d’exploitation prennent en charge les instructions SGX2 avec EDMM sur cette plateforme (en plus d’autres constructions SGX2).
ENCLAVE_TYPE_VBS `0x00000010`	Enclave VBS.

[in] lpEnclaveInformation

Pointeur vers les informations spécifiques à l’architecture à utiliser pour créer l’enclave.

Pour les types d’enclaves ENCLAVE_TYPE_SGX et ENCLAVE_TYPE_SGX2 , vous devez spécifier un pointeur vers une structure ENCLAVE_CREATE_INFO_SGX .

Pour le type d’enclave ENCLAVE_TYPE_VBS , vous devez spécifier un pointeur vers une structure ENCLAVE_CREATE_INFO_VBS .

[in] dwInfoLength

Longueur de la structure vers laquelle pointe le paramètre lpEnclaveInformation , en octets. Pour les types d’enclave ENCLAVE_TYPE_SGX et ENCLAVE_TYPE_SGX2 , cette valeur doit être 4096. Pour le type d’enclave ENCLAVE_TYPE_VBS , cette valeur doit être sizeof(ENCLAVE_CREATE_INFO_VBS), qui est de 36 octets.

[out, optional] lpEnclaveError

Pointeur facultatif vers une variable qui reçoit un code d’erreur d’enclave spécifique à l’architecture. Pour les types d’enclave ENCLAVE_TYPE_SGX, ENCLAVE_TYPE_SGX2 et ENCLAVE_TYPE_VBS , le paramètre lpEnclaveError n’est pas utilisé.

Valeur retournée

Si la fonction réussit, la valeur de retour est l’adresse de base de l’enclave créée.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Pour obtenir la liste des codes d’erreur courants, consultez Codes d’erreur système. Les codes d’erreur suivants s’appliquent également à cette fonction.

Code de retour	Description
ERROR_NOT_SUPPORTED	Un type d’enclave non pris en charge a été spécifié.
ERROR_BAD_LENGTH	La valeur du paramètre dwInfoLength ne correspondait pas à la valeur attendue en fonction de la valeur spécifiée pour le paramètre lpEnclaveInformation .

Remarques

Pour charger des données dans une enclave après les avoir créées, appelez LoadEnclaveData. Pour initialiser l’enclave après avoir chargé les données, appelez InitializeEnclave.

Windows 10, version 1709 : pour supprimer l’enclave lorsque vous avez terminé de l’utiliser, appelez DeleteEnclave. Vous ne pouvez pas supprimer une enclave VBS en appelant la fonction VirtualFree ou VirtualFreeEx . Vous pouvez toujours supprimer une enclave SGX en appelant VirtualFree ou VirtualFreeEx.

Windows 10, version 1507, Windows 10, version 1511, Windows 10, version 1607 et Windows 10, version 1703 : pour supprimer l’enclave lorsque vous avez terminé de l’utiliser, appelez la fonction VirtualFree ou VirtualFreeEx et spécifiez les valeurs suivantes :

Adresse de base de l’enclave pour le paramètre lpAddress .
0 pour le paramètre dwSize .
MEM_RELEASE pour le paramètre dwFreeType . La valeur MEM_DECOMMIT n’est pas prise en charge pour les enclaves.

Pour plus d’informations sur l’extension d’architecture Intel Software Guard Extensions (SGX), consultez Extensions Intel Software Guard.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 10 [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2016 [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	enclaveapi.h (inclure Winbase.h)
Bibliothèque	Kernel32.lib
DLL	Api-ms-win-core-enclave-l1-1-0.dll ; Kernel32.dll ; KernelBase.dll