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 dacl (Discretionary Access Control List) des vorhandenen Tokens, um zu bestimmen, welche Rechte dem neuen Token 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. 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 Besitzinformationen 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 dem neuen Token dieses Recht nur, wenn die berechtigung SE_SECURITY_NAME im Zugriffstoken des aufrufenden Threads aktiviert ist. |
| STANDARD_RIGHTS_READ | Derzeit wird für die gleiche READ_CONTROL definiert. |
| STANDARD_RIGHTS_WRITE | Derzeit wird für die gleiche READ_CONTROL definiert. |
| STANDARD_RIGHTS_EXECUTE | Derzeit wird für die gleiche 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. Somit 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 dem neuen Token dieses Recht nur, 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 dem neuen Token dieses Recht nur, wenn die SE_ASSIGNPRIMARYTOKEN_NAME-Berechtigung im Zugriffstoken des aufrufenden Threads aktiviert ist. |
| TOKEN_DUPLICATE | Erforderlich zum Duplizieren eines Zugriffstokens. 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 zum Abfragen eines Zugriffstokens. |
| 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 SYNCHRONIZE-Recht nicht unterstützen.
[in] ObjectAttributes
Zeiger auf eine OBJECT_ATTRIBUTES-Struktur , die die angeforderten Eigenschaften für das neue Token beschreibt. Der Parameter ObjectAttributes ist optional und kann NULL sein. Wenn der ObjectAttributes-Parameter NULL ist oder wenn der SecurityDescriptor-Member der Struktur, auf die der ObjectAttributes-Parameter verweist, NULL ist, empfängt das neue Token einen Standardsicherheitsdeskriptor, und das neue Tokenhandle kann nicht geerbt werden. In diesem Fall wird dieser Standardsicherheitsdeskriptor aus der Benutzergruppe, der primären Gruppe und den DACL-Informationen erstellt, die im Token des Aufrufers gespeichert sind.
Wenn der TokenType-Parameter auf TokenImpersonation festgelegt ist:
Der Parameter ObjectAttributes kann verwendet werden, um die Identitätswechselebene des neuen Tokens anzugeben. Dies kann erreicht werden, indem ObjectAttributes-SecurityQualityOfService.ImpersonationLevel> auf einen geeignetenSECURITY_IMPERSONATION_LEVEL Enumerationswert festgelegt wird. 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 der effektive (derzeit aktivierte) Teil des Tokens dupliziert werden soll. Wenn dieser Wert auf TRUE festgelegt ist, werden nur die aktuell aktivierten Teile des Quelltokens dupliziert. Wenn dieser Wert 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 beispielsweise EffectiveOnly auf TRUE festgelegt ist, kann 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, der 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. Mögliche Fehlerrückgabecodes sind:
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_ACCESS_VIOLATION | Es ist eine Speicherzugriffsverletzung aufgetreten. Wenn beispielsweise der vorherige Modus 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 Membern dieser Struktur finden Sie unter SECURITY_QUALITY_OF_SERVICE.
Das SecurityQualityOfService-Element muss nach dem Aufruf des InitializeObjectAttributes-Makros festgelegt werden, da InitializeObjectAttributesSecurityQualityOfService derzeit auf NULL festlegt.
Informationen zum Benutzermodus-Analog von ZwDuplicateToken finden Sie unter DuplicateTokenEx.
Wenn Sie die Verwendung des neuen Tokens abgeschlossen 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, wie 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 systemeigenen 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 | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für