Freigeben über


ZwDuplicateToken-Funktion (ntifs.h)

Die ZwDuplicateToken-Funktion erstellt ein Handle für ein neues Zugriffstoken , das ein vorhandenes Token dupliziert. Diese Funktion kann entweder ein primäres Token oder ein Identitätswechseltoken erstellen.

Syntax

NTSYSAPI NTSTATUS ZwDuplicateToken(
  [in]  HANDLE             ExistingTokenHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  BOOLEAN            EffectiveOnly,
  [in]  TOKEN_TYPE         TokenType,
  [out] PHANDLE            NewTokenHandle
);

Parameter

[in] ExistingTokenHandle

Ein Handle für ein vorhandenes Zugriffstoken, das mit dem zugriffsrecht TOKEN_DUPLICATE geöffnet wurde. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in] DesiredAccess

Bitmaske, die die angeforderten Zugriffsrechte für das neue Token angibt. ZwDuplicateToken vergleicht die angeforderten Zugriffsrechte mit der diskretionären Zugriffssteuerungsliste (DACL) des vorhandenen Tokens, um zu ermitteln, welche Rechte dem neuen Token gewährt oder verweigert werden. Geben Sie null an, um dieselben Zugriffsrechte wie das vorhandene Token anzufordern. Um alle Zugriffsrechte anzufordern, die für den Aufrufer gültig sind, geben Sie MAXIMUM_ALLOWED an. Dieser Parameter ist optional und kann entweder null, MAXIMUM_ALLOWED oder eine bitweise OR-Kombination aus einem oder mehreren der folgenden Werte sein:

Wert Bedeutung
Delete Erforderlich, um das Objekt zu löschen.
READ_CONTROL Erforderlich, um die DACL- und Besitzinformationen für das Objekt zu lesen. Informationen zum Zugriff auf die Systemzugriffssteuerungsliste (SACL) finden Sie weiter unten in dieser Tabelle unter ACCESS_SYSTEM_SECURITY.
WRITE_DAC Erforderlich, um die DACL-Informationen für das Objekt zu ändern.
WRITE_OWNER Erforderlich, um die Besitzerinformationen im Sicherheitsdeskriptor (SECURITY_DESCRIPTOR) des Objekts zu ändern.
ACCESS_SYSTEM_SECURITY Erforderlich, um die SACL in der ACL eines Objekts abzurufen oder festzulegen. Das Betriebssystem gewährt dieses Recht nur für das neue Token, wenn die SE_SECURITY_NAME-Berechtigung im Zugriffstoken des aufrufenden Threads aktiviert ist.
STANDARD_RIGHTS_READ Derzeit wird für gleich READ_CONTROL definiert.
STANDARD_RIGHTS_WRITE Derzeit wird für gleich READ_CONTROL definiert.
STANDARD_RIGHTS_EXECUTE Derzeit wird für gleich READ_CONTROL definiert.
STANDARD_RIGHTS_REQUIRED Kombiniert DELETE-, READ_CONTROL-, WRITE_DAC- und WRITE_OWNER-Zugriff.
STANDARD_RIGHTS_ALL Kombiniert DELETE-, READ_CONTROL-, WRITE_DAC-, WRITE_OWNER- und SYNCHRONIZE-Zugriff. Der SYNCHRONIZE-Wert gilt jedoch nicht für Tokenobjekte. Daher verfügt STANDARD_RIGHTS_ALL über ein funktionales Äquivalent zu STANDARD_RIGHTS_REQUIRED.
TOKEN_ADJUST_DEFAULT Erforderlich, um den Standardbesitzer, die primäre Gruppe oder die DACL eines Zugriffstokens zu ändern.
TOKEN_ADJUST_GROUPS Erforderlich, um die Attribute der Gruppen in einem Zugriffstoken anzupassen.
TOKEN_ADJUST_PRIVILEGES Erforderlich, um die Berechtigungen in einem Zugriffstoken zu aktivieren oder zu deaktivieren.
TOKEN_ADJUST_SESSIONID Erforderlich, um die Sitzungs-ID (SID) eines Zugriffstokens anzupassen. Das Betriebssystem gewährt dieses Recht nur dann für das neue Token, wenn die SE_TCB_NAME-Berechtigung im Zugriffstoken des aufrufenden Threads aktiviert ist.
TOKEN_ASSIGN_PRIMARY Erforderlich, um ein primäres Token an einen Prozess anzufügen. Das Betriebssystem gewährt dieses Recht nur dann für das neue Token, wenn die SE_ASSIGNPRIMARYTOKEN_NAME-Berechtigung im Zugriffstoken des aufrufenden Threads aktiviert ist.
TOKEN_DUPLICATE Erforderlich, um ein Zugriffstoken zu duplizieren. Beachten Sie, dass das angegebene ExistingTokenHandle-Token dieses Recht enthalten muss, um diese Routine erfolgreich verwenden zu können.
TOKEN_EXECUTE Kombiniert STANDARD_RIGHTS_EXECUTE und TOKEN_IMPERSONATE.
TOKEN_IMPERSONATE Erforderlich, um einem Prozess ein Identitätswechsel-Zugriffstoken anzufügen.
TOKEN_QUERY Erforderlich, um ein Zugriffstoken abzufragen.
TOKEN_QUERY_SOURCE Erforderlich, um die Quelle eines Zugriffstokens abzufragen.
TOKEN_READ Kombiniert STANDARD_RIGHTS_READ und TOKEN_QUERY.
TOKEN_WRITE Kombiniert STANDARD_RIGHTS_WRITE, TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS und TOKEN_ADJUST_DEFAULT.
TOKEN_ALL_ACCESS Kombiniert alle möglichen Tokenzugriffsberechtigungen für ein Token.

Weitere Informationen finden Sie unter Zugriffsrechte für Access-Token-Objekte im Windows SDK. Beachten Sie, dass Zugriffstoken das Recht SYNCHRONIZE nicht unterstützen.

[in] ObjectAttributes

Zeiger auf eine OBJECT_ATTRIBUTES-Struktur , die die angeforderten Eigenschaften für das neue Token beschreibt. Der ObjectAttributes-Parameter ist optional und kann NULL sein. Wenn der ObjectAttributes-Parameter NULL ist oder das SecurityDescriptor-Element der Struktur, auf das vom ObjectAttributes-Parameter verwiesen wird, NULL ist, empfängt das neue Token einen Standardsicherheitsdeskriptor, und das neue Tokenhandle kann nicht geerbt werden. In diesem Fall wird dieser Standardsicherheitsdeskriptor aus den Benutzergruppen-, primären Gruppen- und DACL-Informationen erstellt, die im Token des Aufrufers gespeichert sind.

Wenn der TokenType-Parameter auf TokenImpersonation festgelegt ist:

  • Der ObjectAttributes-Parameter kann verwendet werden, um die Identitätswechselebene des neuen Tokens anzugeben. Dies kann erreicht werden, indem Sie ObjectAttributes-SecurityQualityOfService.ImpersonationLevel >auf einen entsprechenden SECURITY_IMPERSONATION_LEVEL-Enumerationswert festlegen. Weitere Informationen finden Sie unter SECURITY_QUALITY_OF_SERVICE.

  • Wenn das vorhandene Token ein Identitätswechseltoken ist und der ObjectAttributes-Parameter keine Identitätswechselinformationen bereitstellt, wird die Identitätswechselebene des neuen Tokens auf die Identitätswechselebene des vorhandenen Tokens festgelegt.

  • Wenn das vorhandene Token ein primäres Token ist und keine Informationen zur Identitätswechselebene bereitgestellt werden, weist das neue Identitätswechseltoken eine SECURITY_IMPERSONATION_LEVEL Identitätswechselebene auf.

[in] EffectiveOnly

Ein boolescher Wert, der angibt, ob das gesamte vorhandene Token in das neue Token oder nur in den effektiven (derzeit aktivierten) Teil des Tokens dupliziert werden soll. Wenn auf TRUE festgelegt ist, werden nur die aktuell aktivierten Teile des Quelltokens dupliziert. Wenn auf FALSE festgelegt ist, wird das gesamte vorhandene Token dupliziert. Dadurch kann ein Aufrufer eines geschützten Subsystems einschränken, welche optionalen Gruppen und Berechtigungen dem geschützten Subsystem zur Verfügung gestellt werden. Wenn EffectiveOnly beispielsweise TRUE ist, könnte der Aufrufer ein Token duplizieren, aber die Gruppe Administratoren und das SeTcbPrivilege-Recht entfernen. Das resultierende Token könnte dann an einen untergeordneten Prozess (CreateProcessAsUser) übergeben werden, was die Möglichkeiten des untergeordneten Prozesses einschränken würde. Dieser Parameter ist erforderlich.

[in] TokenType

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

Wert Bedeutung
TokenPrimary Das neue Token ist ein primäres Token. Wenn das vorhandene Token ein Identitätswechseltoken ist, muss das vorhandene Identitätswechseltoken über eine Identitätswechselebene (wie vom ObjectAttributes-Parameter bereitgestellt) von SecurityImpersonation oder SecurityDelegation verfügen. Andernfalls gibt ZwDuplicateToken STATUS_BAD_IMPERSONATION_LEVEL zurückgegeben wird.
TokenImpersonation Das neue Token ist ein Identitätswechseltoken. Wenn das vorhandene Token ein Identitätswechseltoken ist, darf die angeforderte Identitätswechselebene (wie vom ObjectAttributes-Parameter bereitgestellt) des neuen Tokens nicht größer als die Identitätswechselebene des vorhandenen Tokens sein. Andernfalls gibt ZwDuplicateToken STATUS_BAD_IMPERSONATION_LEVEL zurück.

Der TokenType-Parameter ist erforderlich und darf nicht NULL sein.

[out] NewTokenHandle

Ein Zeiger auf eine vom Aufrufer zugewiesene Variable vom Typ HANDLE, die ein Handle auf das neue Token empfängt. Dieser Parameter ist erforderlich und darf nicht NULL sein.

Rückgabewert

ZwDuplicateToken gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Folgende Fehlerrückgabecodes sind möglich:

Rückgabecode Beschreibung
STATUS_ACCESS_VIOLATION Es ist eine Speicherzugriffsverletzung aufgetreten. Wenn der vorherige Modus beispielsweise benutzermodus war und ungültiger Benutzermodusspeicher bereitgestellt wurde, gibt ZwDuplicateToken STATUS_ACCESS_VIOLATION zurück.
STATUS_INSUFFICIENT_RESOURCES Für das Duplizieren des neuen Tokens konnte nicht genügend Arbeitsspeicher zugewiesen werden.
STATUS_INVALID_PARAMETER Ein ungültiger Parameter wurde erkannt.
STATUS_BAD_IMPERSONATION_LEVEL Die angeforderte Identitätswechselebene für das neue Token ist größer als die Identitätswechselebene des vorhandenen Tokens.
STATUS_ACCESS_DENIED ZwDuplicateToken gibt STATUS_ACCESS_DENIED zurück, wenn es nicht auf ExistingTokenHandle zugreifen konnte. Dies tritt auf, wenn das vorhandene Token nicht über das TOKEN_DUPLICATE-Zugriffsrecht verfügt.
STATUS_INVALID_HANDLE ZwDuplicateToken gibt STATUS_INVALID_HANDLE zurück, wenn ExistingTokenHandle auf ein ungültiges Handle verweist.

Hinweise

Wenn vom ObjectAttributes-Parameter keine Informationen zur Identitätswechselebene bereitgestellt wurden, wird die Identitätswechselebene des vorhandenen Tokens für das neue Token verwendet.

In Bezug auf die Struktur, auf die der optionale ObjectAttributes-Parameter verweist, verweist das SecurityQualityOfService-Element von OBJECT_ATTRIBUTES auf eine Struktur vom Typ SECURITY_QUALITY_OF_SERVICE. Informationen zu den Elementen dieser Struktur finden Sie unter SECURITY_QUALITY_OF_SERVICE .

Das SecurityQualityOfService-Element muss nach dem Aufrufen des InitializeObjectAttributes-Makros festgelegt werden, da InitializeObjectAttributesSecurityQualityOfService derzeit auf NULL festlegt.

Informationen zum Benutzermodus-Analog von ZwDuplicateToken finden Sie unter DuplicateTokenEx.

Wenn Sie das neue Token verwendet haben, rufen Sie die ZwClose-Funktion auf, um das Tokenhandle zu schließen.

Wenn der Aufruf der ZwDuplicateToken-Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtDuplicateToken" anstelle von "ZwDuplicateToken" verwenden.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx - und ZwXxx-Versionen einer Windows Native System Services-Routine anders verhalten, da sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und ZwXxx-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000
Zielplattform Universell
Header ntifs.h (include Ntifs.h, FltKernel.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI-Complianceregeln HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

Weitere Informationen

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

SECURITY_IMPERSONATION_LEVEL