DuplicateTokenEx-Funktion (securitybaseapi.h)

Artikel
11/20/2024

Die DuplicateTokenEx--Funktion erstellt ein neues Zugriffstoken, das ein vorhandenes Token dupliziert. Diese Funktion kann entweder ein primäres Token oder ein Identitätswechseltokenerstellen.

Syntax

BOOL DuplicateTokenEx(
  [in]           HANDLE                       hExistingToken,
  [in]           DWORD                        dwDesiredAccess,
  [in, optional] LPSECURITY_ATTRIBUTES        lpTokenAttributes,
  [in]           SECURITY_IMPERSONATION_LEVEL ImpersonationLevel,
  [in]           TOKEN_TYPE                   TokenType,
  [out]          PHANDLE                      phNewToken
);

Parameter

[in] hExistingToken

Ein Handle für ein Zugriffstoken, das mit TOKEN_DUPLICATE Zugriff geöffnet wurde.

[in] dwDesiredAccess

Gibt die angeforderten Zugriffsrechte für das neue Token an. Die DuplicateTokenEx--Funktion vergleicht die angeforderten Zugriffsrechte mit der liste der ermessensberechtigten Zugriffssteuerungsliste (DACL) des vorhandenen Tokens, um zu bestimmen, welche Rechte gewährt oder verweigert werden. Geben Sie null an, um die gleichen Zugriffsrechte wie das vorhandene Token anzufordern. Geben Sie MAXIMUM_ALLOWED an, um alle Für den Aufrufer gültigen Zugriffsrechte anzufordern.

Eine Liste der Zugriffsrechte für Zugriffstoken finden Sie unter Zugriffsrechte für Access-Token Objekte.

[in, optional] lpTokenAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES Struktur, die einen Sicherheitsdeskriptor für das neue Token angibt und bestimmt, ob untergeordnete Prozesse das Token erben können. Wenn lpTokenAttributesNULL-ist, erhält das Token einen Standardsicherheitsdeskriptor, und der Handle kann nicht geerbt werden. Wenn der Sicherheitsdeskriptor eine Systemzugriffssteuerungsliste (SACL) enthält, erhält das Token ACCESS_SYSTEM_SECURITY Zugriffsrecht, auch wenn es in dwDesiredAccessnicht angefordert wurde.

Um den Besitzer im Sicherheitsdeskriptor für das neue Token festzulegen, muss das Prozesstoken des Aufrufers über den SE_RESTORE_NAME Berechtigungssatz verfügen.

[in] ImpersonationLevel

Gibt einen Wert aus der SECURITY_IMPERSONATION_LEVEL-Aufzählung an, der die Identitätswechselebene des neuen Tokens angibt.

[in] TokenType

Gibt einen der folgenden Werte aus der TOKEN_TYPE-Aufzählung an.

Wert	Bedeutung
TokenPrimary-	Das neue Token ist ein primären Token, das Sie in der CreateProcessAsUser--Funktion verwenden können.
TokenImpersonation	Das neue Token ist ein Identitätswechseltoken.

[out] phNewToken

Ein Zeiger auf eine HANDLE Variable, die das neue Token empfängt.

Wenn Sie mit der Verwendung des neuen Tokens fertig sind, rufen Sie die CloseHandle-Funktion auf, um das Tokenhandle zu schließen.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion einen Wert ungleich Null zurück.

Wenn die Funktion fehlschlägt, wird null zurückgegeben. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Mit der DuplicateTokenEx--Funktion können Sie ein primäres Token erstellen, das Sie in der CreateProcessAsUser--Funktion verwenden können. Dadurch kann eine Serveranwendung, die den Identitätswechsel eines Clients angibt, einen Prozess erstellen, der den Sicherheitskontext des Clients aufweist. Beachten Sie, dass die funktion DuplicateToken nur Identitätswechseltoken erstellen kann, die für CreateProcessAsUserungültig sind.

Es folgt ein typisches Szenario für die Verwendung von DuplicateTokenEx- zum Erstellen eines primären Tokens. Eine Serveranwendung erstellt einen Thread, der eine der Identitätswechselfunktionen aufruft, z. B. ImpersonateNamedPipeClient, um einen Client imitieren zu können. Der Identitätswechselthread ruft dann die OpenThreadToken--Funktion auf, um ein eigenes Token abzurufen, bei dem es sich um ein Identitätswechseltoken handelt, das den Sicherheitskontext des Clients aufweist. Der Thread gibt dieses Identitätswechseltoken in einem Aufruf von DuplicateTokenExan, der das TokenPrimary-Flag angibt. Die funktion DuplicateTokenEx erstellt ein primäres Token mit dem Sicherheitskontext des Clients.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	securitybaseapi.h (include Windows.h)
Library	Advapi32.lib
DLL-	Advapi32.dll