NtQueryInformationToken-Funktion (ntifs.h)
Die NtQueryInformationToken Routine ruft einen bestimmten Informationstyp zu einem Zugriffstoken ab. Der Anrufvorgang muss über geeignete Zugriffsrechte verfügen, um die Informationen zu erhalten.
Syntax
__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationToken(
[in] HANDLE TokenHandle,
[in] TOKEN_INFORMATION_CLASS TokenInformationClass,
[out] PVOID TokenInformation,
[in] ULONG TokenInformationLength,
[out] PULONG ReturnLength
);
Parameter
[in] TokenHandle
Behandeln Sie 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 über TOKEN_QUERY Zugriff verfügen. 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 Aufzählungstyp, der den abzurufenden Informationstyp identifiziert. Die möglichen Werte für diesen Parameter werden in der TokenInformationClass Wertspalte der Tabelle aufgeführt, die in der Beschreibung des TokenInformation-Parameters angezeigt wird.
[out] TokenInformation
Zeigen Sie 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 TokenInformationClassab, wie in der folgenden Tabelle dargestellt. Alle Strukturen müssen an einer 32-Bit-Grenze ausgerichtet werden.
| TokenInformationClass-Wert | Effekt auf TokenInformation-Puffer |
|---|---|
| TokenDefaultDacl- | Der Puffer empfängt eine TOKEN_DEFAULT_DACL Struktur, die die standardmäßige DACL- für neu erstellte Objekte enthält. |
| TokenGroups | Der Puffer empfängt eine TOKEN_GROUPS Struktur, die die gruppenkonten enthält, die dem Token zugeordnet sind. |
| 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 NtQueryInformationToken fehl. |
| TokenOwner- | Der Puffer empfängt eine TOKEN_OWNER Struktur, die den 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 Dem Token zugeordneten Sitzungsbezeichner für Terminaldienste angibt. Wenn das Token der TerminalServer-Konsolensitzung zugeordnet ist, ist der Sitzungsbezeichner null. Ein Nichtzero-Sitzungsbezeichner gibt eine Terminaldienste-Clientsitzung an. In einer Umgebung ohne Terminaldienste ist der Sitzungsbezeichner null. |
| 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 das Token ein primäres Token oder Identitätswechseltoken ist. |
| 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 im TokenInformation Puffer keine Daten 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 TokenInformationClass- ist TokenDefaultDacl, und für das Token ist keine STANDARD-DACL eingerichtet. In diesem Fall erhält ReturnLength- Null.
Rückgabewert
NtQueryInformationToken gibt STATUS_SUCCESS oder einen entsprechenden Fehlerstatus zurück. Mögliche Fehlerstatuscodes sind:
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_ACCESS_DENIED | TokenHandle- nicht über den erforderlichen Zugriff verfügt. |
| 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_ACCESS_VIOLATION | ReturnLength- null war oder nicht schreibbar war, um die tatsächliche Länge der Informationen zu erhalten, die durch TokenInformation. |
| STATUS_INVALID_HANDLE | TokenHandle- war kein gültiger Handle. |
| STATUS_INVALID_INFO_CLASS | TokenInformationClass war keine gültige Tokeninformationsklasse. |
| STATUS_OBJECT_TYPE_MISMATCH | TokenHandle- kein Tokenhandle war. |
Bemerkungen
Die NtQueryInformationToken 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 NtQueryInformationTokenü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 dem Benutzer SID-.
Aufgrund der Art der Tokeneigenschaften (z. B. Tokenbenutzer, primäre Tokengruppe, Berechtigungen usw.), bei denen derEn Inhalt je nach Token variieren kann), ist ReturnLength- nicht optional; das heißt, es darf nicht NULL sein. Dies liegt daran, dass SID eine Struktur mit variabler Länge ist, während eine bestimmte Berechtigung in einem Token, aber nicht in einer anderen vorhanden sein kann (die Berechtigungsanzahl kann für jedes Token unterschiedlich sein). Es liegt in der Verantwortung des Aufrufers, zuerst die erforderliche Längengröße abzufragen, um Speicher zur Aufnahme der angeforderten Tokeninformationen zuzuweisen, bevor die tatsächliche Abfrage ausgeführt wird. Das heißt, es liegt auch in der Verantwortung des Aufrufers, eine gültige ReturnLength- Variable bereitzustellen, die schreibbar und nicht NULL ist. In einem NULL-Fallszenario löst die Funktion eine Zugriffsverletzungs exception aus.
Weitere Informationen zur Sicherheits- und Zugriffssteuerung finden Sie unter Windows-Sicherheitsmodell für Treiberentwickler und die Dokumentation zu diesen Themen im Windows SDK.
Anmerkung
Wenn der Aufruf der NtQueryInformationToken--Funktion im Benutzermodus auftritt, 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, 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 XP |
| Zielplattform- | Universal |
| Header- | ntifs.h (einschließlich Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | PASSIVE_LEVEL |
| DDI-Complianceregeln | HwStorPortProhibitedDIs, PowerIrpDDis |