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 TOKEN_DUPLICATE Zugriffsrecht 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 bestimmen, welche Rechte dem neuen Token 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. Dieser Parameter ist optional und kann entweder Null, MAXIMUM_ALLOWED oder eine bitweise ODER Kombination aus einem oder mehreren der folgenden Werte sein:
| Wert | Bedeutung |
|---|---|
| LÖSCHEN | Erforderlich, um das Objekt zu löschen. |
| READ_CONTROL | Erforderlich, um die DACL- und Besitzerinformationen für das Objekt zu lesen. Informationen zum Zugriff auf die Systemzugriffssteuerungsliste (SACL) finden Sie in ACCESS_SYSTEM_SECURITY weiter unten in dieser Tabelle. |
| WRITE_DAC | Erforderlich, um die DACL-Informationen für das Objekt zu ändern. |
| WRITE_OWNER | Erforderlich, um die Besitzerinformationen im Sicherheitsdeskriptor des Objekts zu ändern (SECURITY_DESCRIPTOR). |
| ACCESS_SYSTEM_SECURITY | Erforderlich, um die SACL in der ACL eines Objekts abzurufen oder festzulegen. Das Betriebssystem gewährt diesem Recht nur dann das neue Token, wenn das SE_SECURITY_NAME-Berechtigung im Zugriffstoken des aufrufenden Threads aktiviert ist. |
| STANDARD_RIGHTS_READ | Derzeit definiert auf den gleichen READ_CONTROL. |
| STANDARD_RIGHTS_WRITE | Derzeit definiert auf den gleichen READ_CONTROL. |
| STANDARD_RIGHTS_EXECUTE | Derzeit definiert auf den gleichen READ_CONTROL. |
| 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 hat STANDARD_RIGHTS_ALL eine funktionell gleichwertige 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 diesem Recht nur dann das neue Token, wenn das SE_TCB_NAME-Privileg 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 diesem Recht nur dann das neue Token, wenn das 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 zu verwenden. |
| TOKEN_EXECUTE | Kombiniert STANDARD_RIGHTS_EXECUTE und TOKEN_IMPERSONATE. |
| TOKEN_IMPERSONATE | Erforderlich zum Anfügen eines Identitätswechselzugriffstokens an einen Prozess. |
| 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 SYNCHRONIZE-Recht nicht unterstützen.
[in] ObjectAttributes
Zeigen Sie 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 wenn der SecurityDescriptor Element der Struktur, auf das der ObjectAttributes-Parameter verweist, NULL ist, empfängt das neue Token einen Standardsicherheitsdeskriptor, und der 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 parameter TokenType auf TokenImpersonationfestgelegt 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 parameter ObjectAttributes 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 Identitätswechselebeneninformationen bereitgestellt werden, verfügt das neue Identitätswechseltoken über eine SECURITY_IMPERSONATION_LEVEL Identitätswechselebene.
[in] EffectiveOnly
Ein boolescher Wert, der angibt, ob das gesamte vorhandene Token in das neue Token oder nur den effektiven (derzeit aktivierten) Teil des Tokens dupliziert werden soll. Wenn dieser Wert auf TRUE festgelegt ist, werden nur die derzeit aktivierten Teile des Quelltokens dupliziert. Bei Festlegung auf FALSE wird das gesamte vorhandene Token dupliziert. Dies bietet eine Möglichkeit für einen Aufrufer eines geschützten Subsystems, um zu begrenzen, welche optionalen Gruppen und Berechtigungen für das geschützte Subsystem zur Verfügung gestellt werden. Wenn beispielsweise EffectiveOnly WAHR ist, könnte der Aufrufer ein Token duplizieren, aber die Gruppe "Administratoren" und das SeTcbPrivilege-Recht entfernen. Das resultierende Token kann dann an einen untergeordneten Prozess (CreateProcessAsUser) übergeben werden, wodurch der untergeordnete Prozess eingeschränkt werden kann. Dieser Parameter ist erforderlich.
[in] TokenType
Gibt einen der folgenden Werte aus der TOKEN_TYPE-Aufzählung an.
| Wert | Bedeutung |
|---|---|
| TokenPrimary- | Das neue Token ist ein primäres Token. Wenn es sich bei dem vorhandenen Token um ein Identitätswechseltoken handelt, muss das vorhandene Identitätswechseltoken eine Identitätswechselebene (wie vom parameter ObjectAttributes) SecurityImpersonation- oder SecurityDelegation-angegeben haben. Andernfalls wird ZwDuplicateToken zurückgegeben, STATUS_BAD_IMPERSONATION_LEVEL zurückgegeben wird. |
| TokenImpersonation | Das neue Token ist ein Identitätswechseltoken. Wenn es sich bei dem vorhandenen Token um ein Identitätswechseltoken handelt, darf die angeforderte Identitätswechselebene (wie vom parameter ObjectAttributes) 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 an 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ücklaufcodes sind:
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_ACCESS_VIOLATION | Es ist ein Speicherzugriffsverstoß aufgetreten. Wenn beispielsweise der vorherige Modus benutzermodus war und ungültiger Benutzermodusspeicher bereitgestellt wurde, gibt ZwDuplicateToken STATUS_ACCESS_VIOLATION zurück. |
| STATUS_INSUFFICIENT_RESOURCES | Genügend Arbeitsspeicher konnte nicht für das Duplizieren des neuen Tokens 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 ExistingTokenHandlezugreifen konnte. Dies würde auftreten, 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 einen ungültigen Handle verweist. |
Bemerkungen
Wenn vom parameter ObjectAttributes parameter keine Identitätswechselebene bereitgestellt wurde, wird die Identitätswechselebene des vorhandenen Tokens für das neue Token verwendet.
In Bezug auf die Struktur, auf die durch den optionalen ObjectAttributes Parameter verwiesen wird, verweist das SecurityQualityOfService Member von OBJECT_ATTRIBUTES auf eine Struktur vom Typ SECURITY_QUALITY_OF_SERVICE. Informationen zu den Mitgliedern dieser Struktur finden Sie unter SECURITY_QUALITY_OF_SERVICE.
Das SecurityQualityOfService-Element muss festgelegt werden, nachdem das makro InitializeObjectAttributes aufgerufen wurde, da InitializeObjectAttributes derzeit SecurityQualityOfService- auf NULL festlegt.
Informationen zum Benutzermodus analog zu ZwDuplicateTokenfinden Sie unter DuplicateTokenEx.
Wenn Sie mit der Verwendung des neuen Tokens fertig sind, rufen Sie die ZwClose-Funktion auf, um den Tokenhandle zu schließen.
Wenn der Aufruf der ZwDuplicateToken--Funktion im Benutzermodus auftritt, 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 behandeln und interpretieren. Weitere Informationen zur Beziehung zwischen den NtXxx und ZwXxx- Versionen einer Routine finden Sie unter Using Nt and Zw Versions of the Native System Services Routines.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 2000 |
| Zielplattform- | Universal |
| Header- | ntifs.h (einschließlich Ntifs.h, FltKernel.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | PASSIVE_LEVEL |
| DDI-Complianceregeln | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |