NtDuplicateToken-Funktion (ntifs.h)
Die NtDuplicateToken-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
__kernel_entry NTSYSCALLAPI NTSTATUS NtDuplicateToken(
[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 kann nicht NULL sein.
[in] DesiredAccess
Bitmaske, die die angeforderten Zugriffsrechte für das neue Token angibt. NtDuplicateToken vergleicht die angeforderten Zugriffsrechte mit der diskretionären Zugriffssteuerungsliste (Discretionary Access Control List, 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. 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 NtDuplicateToken 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 NtDuplicateToken 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
NtDuplicateToken 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 NtDuplicateToken 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 | NtDuplicateToken konnte nicht auf ExistingTokenHandle zugreifen. Dies tritt auf, wenn das vorhandene Token nicht über das TOKEN_DUPLICATE-Zugriffsrecht verfügt. |
| STATUS_INVALID_HANDLE | ExistingTokenHandle bezieht sich auf ein ungültiges Handle. |
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 zur Benutzermodus-Analogie von NtDuplicateToken finden Sie unter DuplicateTokenEx in der Windows SDK-Dokumentation.
Wenn Sie die Verwendung des neuen Tokens abgeschlossen haben, rufen Sie die NtClose-Funktion auf, um das Tokenhandle zu schließen.
Wenn der Aufruf der NtDuplicateToken-Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtDuplicateToken" anstelle von "NtDuplicateToken" 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, PowerIrpDDis |