DuplicateTokenEx-Funktion (securitybaseapi.h)

Artikel
08/25/2023

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

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 wird.

[in] dwDesiredAccess

Gibt die angeforderten Zugriffsrechte für das neue Token an. Die DuplicateTokenEx-Funktion vergleicht die angeforderten Zugriffsrechte mit der dacl (Discretionary Access Control List ) des vorhandenen Tokens, um zu bestimmen, welche Rechte gewährt oder verweigert werden. Geben Sie null an, um dieselben Zugriffsrechte wie das vorhandene Token anzufordern. Geben Sie MAXIMUM_ALLOWED an, um alle Zugriffsrechte anzufordern, die für den Aufrufer gültig sind.

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

[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, ruft das Token einen Standardsicherheitsdeskriptor ab, und das Handle kann nicht geerbt werden. Wenn der Sicherheitsdeskriptor eine SACL (System Access Control List ) enthält, erhält das Token ACCESS_SYSTEM_SECURITY Zugriffsrecht, auch wenn es in dwDesiredAccess nicht angefordert wurde.

Um den Besitzer im Sicherheitsdeskriptor für das neue Token festzulegen, muss für das Prozesstoken des Aufrufers die berechtigung SE_RESTORE_NAME festgelegt sein.

[in] ImpersonationLevel

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

[in] TokenType

Gibt einen der folgenden Werte aus der TOKEN_TYPE-Enumeration an.

Wert	Bedeutung
TokenPrimary	Das neue Token ist ein primäres 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 die Verwendung des neuen Tokens abgeschlossen haben, 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 0 (null) zurück.

Wenn die Funktion fehlschlägt, wird null zurückgegeben. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

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 die Identität eines Clients angibt, einen Prozess erstellen, der über den Sicherheitskontext des Clients verfügt. Beachten Sie, dass die DuplicateToken-Funktion nur Identitätswechseltoken erstellen kann, die für CreateProcessAsUser ungü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 die Identität eines Clients zu annehmen. Der Identitätswechsel-Thread 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 DuplicateTokenEx an, wobei das TokenPrimary-Flag angegeben wird. Die DuplicateTokenEx-Funktion erstellt ein primäres Token , das über den Sicherheitskontext des Clients verfügt.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	securitybaseapi.h (Einschließen von Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll