Fonction InitializeEnclave (enclaveapi.h)

Article
02/05/2024

Initialise une enclave que vous avez créée et chargée avec des données.

Syntaxe

BOOL InitializeEnclave(
  [in] HANDLE  hProcess,
  [in] LPVOID  lpAddress,
  [in] LPCVOID lpEnclaveInformation,
  [in] DWORD   dwInfoLength,
  [in] LPDWORD lpEnclaveError
);

Paramètres

[in] hProcess

Handle du processus pour lequel l’enclave a été créée.

[in] lpAddress

Toute adresse dans l’enclave.

[in] lpEnclaveInformation

Pointeur vers des informations spécifiques à l’architecture à utiliser pour initialiser l’enclave.

Pour les types d’enclave ENCLAVE_TYPE_SGX et ENCLAVE_TYPE_SGX2 , spécifiez un pointeur vers une structure ENCLAVE_INIT_INFO_SGX .

Pour le type d’enclave ENCLAVE_TYPE_VBS , spécifiez un pointeur vers une structure ENCLAVE_INIT_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_INIT_INFO_VBS), qui est de 8 octets.

[in] 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 et ENCLAVE_TYPE_SGX2 , le paramètre lpEnclaveError contient l’erreur générée par l’instruction EINIT si la fonction échoue et que GetLastError retourne ERROR_ENCLAVE_FAILURE.

Pour le type d’enclave ENCLAVE_TYPE_VBS , le paramètre lpEnclaveError n’est pas utilisé.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro. Si la fonction échoue, la valeur de retour est égale à zéro. 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_ENCLAVE_FAILURE	Une défaillance spécifique à l’architecture d’enclave sous-jacente s’est produite. La valeur du paramètre lpEnclaveError contient l’erreur spécifique à l’architecture. Pour les types d’enclaves ENCLAVE_TYPE_SGX et ENCLAVE_TYPE_SGX2 , l’instruction EINIT que la structure ENCLAVE_INIT_INFO_SGX a spécifiée a généré une erreur. La valeur du paramètre lpEnclaveError contient l’erreur générée par l’instruction.
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 .
ERROR_RETRY	Le processeur n’a pas pu initialiser l’enclave en temps voulu. Essayez à nouveau d’initialiser l’enclave.

Remarques

Pour créer une enclave, utilisez la fonction CreateEnclave . Pour charger des données dans l’enclave avant de les initialiser, utilisez la fonction LoadEnclaveData .

Windows 10, version 1709 et ultérieures et Windows 11 : 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 .

Configuration requise


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