ZwQueryInformationToken-Funktion (ntifs.h)
Die ZwQueryInformationToken-Routine ruft einen angegebenen Typ von Informationen zu einem Zugriffstoken ab. Der aufrufende Prozess muss über geeignete Zugriffsrechte verfügen, um die Informationen abzurufen.
Syntax
NTSYSAPI NTSTATUS ZwQueryInformationToken(
[in] HANDLE TokenHandle,
[in] TOKEN_INFORMATION_CLASS TokenInformationClass,
[out] PVOID TokenInformation,
[in] ULONG TokenInformationLength,
[out] PULONG ReturnLength
);
Parameter
[in] TokenHandle
Handle für ein Zugriffstoken, aus dem Informationen abgerufen werden sollen. Wenn TokenInformationClass auf TokenSource festgelegt ist, muss das Handle über TOKEN_QUERY_SOURCE Zugriff verfügen. Für alle anderen TokenInformationClass-Werte muss das Handle TOKEN_QUERY Zugriff haben. Weitere Informationen zu Zugriffsrechten für Zugriffstokenobjekte finden Sie im Abschnitt Sicherheit der Windows SDK-Dokumentation.
[in] TokenInformationClass
Ein Wert aus dem TOKEN_INFORMATION_CLASS aufgezählten Typ, der den Typ der abzurufenden Informationen angibt. Die möglichen Werte für diesen Parameter werden in der Spalte TokenInformationClass Value der Tabelle aufgeführt, die in der Beschreibung des TokenInformation-Parameters angezeigt wird.
[out] TokenInformation
Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die angeforderten Informationen zum Token empfängt. Die in diesen Puffer eingefügte Struktur hängt vom Wert von TokenInformationClass ab, wie in der folgenden Tabelle gezeigt. Alle Strukturen müssen an einer 32-Bit-Grenze ausgerichtet werden.
| TokenInformationClass-Wert | Auswirkungen auf den TokenInformation-Puffer |
|---|---|
| TokenDefaultDacl | Der Puffer empfängt eine TOKEN_DEFAULT_DACL-Struktur , die die Standard-DACL für neu erstellte Objekte enthält. |
| TokenGruppen | Der Puffer empfängt eine TOKEN_GROUPS-Struktur , die die dem Token zugeordneten Gruppenkonten enthält. |
| TokenImpersonationLevel | Der Puffer empfängt einen SECURITY_IMPERSONATION_LEVEL Wert, der die Identitätswechselebene des Tokens angibt. Wenn das Zugriffstoken kein Identitätswechseltoken ist, schlägt der Aufruf von ZwQueryInformationToken fehl. |
| TokenOwner | Der Puffer empfängt eine TOKEN_OWNER-Struktur , die die Standardbesitzer-SID für neu erstellte Objekte enthält. |
| TokenPrimaryGroup | Der Puffer empfängt eine TOKEN_PRIMARY_GROUP-Struktur , die die Standard-primäre Gruppen-SID für neu erstellte Objekte enthält. |
| TokenPrivileges | Der Puffer empfängt eine TOKEN_PRIVILEGES-Struktur , die die Berechtigungen des Tokens enthält. |
| TokenSessionId | Der Puffer empfängt einen 32-Bit-Wert, der den Terminaldienste-Sitzungsbezeichner angibt, der dem Token zugeordnet ist. Wenn das Token der Terminalserver-Konsolensitzung zugeordnet ist, ist der Sitzungsbezeichner 0. Ein Nichtzero-Sitzungsbezeichner gibt eine Terminaldienste-Clientsitzung an. In einer Umgebung ohne Terminaldienste ist der Sitzungsbezeichner 0. |
| TokenSource | Der Puffer empfängt eine TOKEN_SOURCE Struktur, die die Quelle des Tokens enthält. TOKEN_QUERY_SOURCE Zugriff ist erforderlich, um diese Informationen abzurufen. |
| TokenStatistics | Der Puffer empfängt eine TOKEN_STATISTICS Struktur, die verschiedene Tokenstatistiken enthält. |
| Tokentype | Der Puffer empfängt einen TOKEN_TYPE Wert, der angibt, ob es sich bei dem Token um ein primäres Token oder Identitätswechseltoken handelt. |
| TokenUser | Der Puffer empfängt eine TOKEN_USER-Struktur , die das Benutzerkonto des Tokens enthält. |
[in] TokenInformationLength
Länge des vom Aufrufer zugewiesenen TokenInformation-Puffers in Bytes.
[out] ReturnLength
Zeiger auf eine vom Aufrufer zugewiesene Variable, die die tatsächliche Länge der im TokenInformation-Puffer zurückgegebenen Informationen in Bytes empfängt. Wenn eine der folgenden Bedingungen zutrifft, werden keine Daten im TokenInformation-Puffer zurückgegeben:
Die Größe der angeforderten Tokeninformationsstruktur ist größer als TokenInformationLength. In diesem Fall empfängt ReturnLength die tatsächliche Anzahl von Bytes, die zum Speichern der angeforderten Informationen erforderlich sind.
Der Wert von TokenInformationClass ist TokenDefaultDacl, und für das Token ist keine STANDARD-DACL eingerichtet. In diesem Fall erhält ReturnLength null.
Rückgabewert
ZwQueryInformationToken gibt STATUS_SUCCESS oder einen entsprechenden Fehler status zurück. Mögliche Fehler status Codes sind:
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_ACCESS_DENIED | TokenHandle verfügte nicht über den erforderlichen Zugriff. |
| STATUS_BUFFER_TOO_SMALL | Die Größe der angeforderten Tokeninformationsstruktur ist größer als TokenInformationLength. Die Anzahl der erforderlichen Bytes wird in ReturnLength zurückgegeben. |
| STATUS_INVALID_HANDLE | TokenHandle war kein gültiges Handle. |
| STATUS_INVALID_INFO_CLASS | TokenInformationClass war keine gültige Tokeninformationsklasse. |
| STATUS_OBJECT_TYPE_MISMATCH | TokenHandle war kein Tokenhandle. |
Hinweise
Die ZwQueryInformationToken-Routine kann von einem Dateisystem- oder Dateisystemfiltertreiber verwendet werden, um die SID des Aufrufers zu bestimmen, der die Anforderung während IRP_MJ_CREATE Verarbeitung initiiert hat. Wenn TokenUser für den TokenInformationClass-Parameter angegeben wird, der an ZwQueryInformationToken übergeben wird, wird eine TOKEN_USER Struktur im Puffer zurückgegeben, auf den der TokenInformation-Parameter verweist. Dieser zurückgegebene Puffer enthält eine SID_AND_ATTRIBUTES-Struktur mit der Benutzer-SID.
Weitere Informationen zur Sicherheit und Zugriffssteuerung finden Sie unter Windows-Sicherheitsmodell für Treiberentwickler und in der Dokumentation zu diesen Themen im Windows SDK.
Hinweis
Wenn der Aufruf der ZwQueryInformationToken-Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtQueryInformationToken" anstelle von "ZwQueryInformationToken" 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 XP |
| Zielplattform | Universell |
| Header | ntifs.h (include Ntifs.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI-Complianceregeln | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |