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