CreateEnclave-Funktion (enclaveapi.h)

Artikel
02/26/2024

Erstellt eine neue nicht initialisierte Enklave. Eine Enclave ist eine isolierte Region mit Code und Daten innerhalb des Adressraums einer Anwendung. Nur Code, der innerhalb der Enclave ausgeführt wird, kann auf Daten innerhalb derselben Enclave zugreifen.

Syntax

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

Parameter

[in] hProcess

Ein Handle für den Prozess, für den Sie eine Enclave erstellen möchten.

[in, optional] lpAddress

Die bevorzugte Basisadresse der Enklave. Geben Sie NULL an, damit das Betriebssystem die Basisadresse zuweisen soll.

[in] dwSize

Die Größe der Enklave, die Sie erstellen möchten, einschließlich der Größe des Codes, den Sie in die Enclave laden, in Bytes.

VBS-Enklaven müssen ein Vielfaches von 2 MB groß sein.

SGX-Enklaven müssen eine Leistung von 2 in der Größe aufweisen und ihre Basis muss auf die gleiche Leistung von 2 wie die Größe ausgerichtet sein, mit einer Mindestausrichtung von 2 MB. Wenn die Enclave beispielsweise 128 MB beträgt, muss ihre Basis an einer Grenze von 128 MB ausgerichtet werden.

[in] dwInitialCommitment

Die Menge des Arbeitsspeichers, der für die Enclave committ werden soll, in Bytes.

Wenn die Menge des verfügbaren Enclave-Arbeitsspeichers nicht ausreicht, um diese Anzahl von Bytes zu committen, schlägt die Enclaveerstellung fehl. Jeder Arbeitsspeicher, der beim Initialisieren der Enclave durch Aufrufen von InitializeEnclave nicht verwendet wird, wird in die Liste der freien Seiten zurückgegeben.

Der Wert des dwInitialCommittment-Parameters darf den Wert des dwSize-Parameters nicht überschreiten.

Dieser Parameter wird nicht für virtualisierungsbasierte Sicherheitsenklaven (VBS) verwendet.

[in] flEnclaveType

Der Architekturtyp der Enklave, die Sie erstellen möchten. Um zu überprüfen, ob ein Enclave-Typ unterstützt wird, rufen Sie IsEnclaveTypeSupported auf.

Wert	Bedeutung
ENCLAVE_TYPE_SGX `0x00000001`	Eine Enclave für die Intel Software Guard Extensions (SGX)-Architekturerweiterung.
ENCLAVE_TYPE_SGX2 `0x00000002`	Unterstützt SGX2- und SGX1-Enklaven. Die Plattform und das Betriebssystem unterstützen SGX2-Anweisungen mit EDMM auf dieser Plattform (zusätzlich zu anderen SGX2-Konstrukten).
ENCLAVE_TYPE_VBS `0x00000010`	Eine VBS-Enklave.

[in] lpEnclaveInformation

Ein Zeiger auf die architekturspezifischen Informationen, die zum Erstellen der Enclave verwendet werden sollen.

Für die Enclavetypen ENCLAVE_TYPE_SGX und ENCLAVE_TYPE_SGX2 müssen Sie einen Zeiger auf eine ENCLAVE_CREATE_INFO_SGX-Struktur angeben.

Für den ENCLAVE_TYPE_VBS Enclavetyp müssen Sie einen Zeiger auf eine ENCLAVE_CREATE_INFO_VBS-Struktur angeben.

[in] dwInfoLength

Die Länge der Struktur, auf die der lpEnclaveInformation-Parameter zeigt, in Bytes. Für die Enclavetypen ENCLAVE_TYPE_SGX und ENCLAVE_TYPE_SGX2 muss dieser Wert 4096 sein. Für den ENCLAVE_TYPE_VBS Enclavetyp muss sizeof(ENCLAVE_CREATE_INFO_VBS)dieser Wert sein, d. h. 36 Bytes.

[out, optional] lpEnclaveError

Ein optionaler Zeiger auf eine Variable, die einen architekturspezifischen Enclave-Fehlercode empfängt. Für die ENCLAVE_TYPE_SGX, ENCLAVE_TYPE_SGX2 und ENCLAVE_TYPE_VBS Enclave-Typen wird der lpEnclaveError-Parameter nicht verwendet.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Basisadresse der erstellten Enclave.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Eine Liste allgemeiner Fehlercodes finden Sie unter Systemfehlercodes. Die folgenden Fehlercodes gelten auch für diese Funktion.

Rückgabecode	Beschreibung
ERROR_NOT_SUPPORTED	Es wurde ein nicht unterstützter Enclave-Typ angegeben.
ERROR_BAD_LENGTH	Der Wert des dwInfoLength-Parameters stimmte nicht mit dem wert überein, der basierend auf dem für den parameter lpEnclaveInformation angegebenen Wert erwartet wird.

Hinweise

Um Daten nach der Erstellung in eine Enclave zu laden, rufen Sie LoadEnclaveData auf. Um die Enclave nach dem Laden der Daten zu initialisieren, rufen Sie InitializeEnclave auf.

Windows 10, Version 1709: Um die Enclave nach Abschluss der Verwendung zu löschen, rufen Sie DeleteEnclave auf. Sie können eine VBS-Enclave nicht löschen, indem Sie die Funktion VirtualFree oder VirtualFreeEx aufrufen. Sie können eine SGX-Enklave trotzdem löschen, indem Sie VirtualFree oder VirtualFreeEx aufrufen.

Windows 10, Version 1507, Windows 10, Version 1511, Windows 10, Version 1607 und Windows 10, Version 1703: Rufen Sie die Funktion VirtualFree oder VirtualFreeEx auf, und geben Sie die folgenden Werte an, um die Enclave zu löschen, wenn Sie sie verwenden:

Die Basisadresse der Enclave für den lpAddress-Parameter .
0 für den dwSize-Parameter .
MEM_RELEASE für den dwFreeType-Parameter . Der wert MEM_DECOMMIT wird für Enclaves nicht unterstützt.

Informationen zur Intel Software Guard Extensions (SGX)-Architekturerweiterung finden Sie unter Intel Software Guard-Erweiterungen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 10 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2016 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	enclaveapi.h (einschließlich Winbase.h)
Bibliothek	Kernel32.lib
DLL	Api-ms-win-core-enclave-l1-1-0.dll; Kernel32.dll; KernelBase.dll