NtQueryInformationToken-Funktion (ntifs.h)

Die NtQueryInformationToken-Routine ruft einen angegebenen Informationstyp über ein Zugriffstoken ab. Der Anrufvorgang muss über entsprechende Zugriffsrechte verfügen, um die Informationen abzurufen.

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 der Handle über TOKEN_QUERY_SOURCE Zugriff verfügen. Für alle anderen TokenInformationClass-Werte muss der 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 aufgezählten Typ, der die Art der abgerufenen Informationen identifiziert. 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 zugeordneten Anruferpuffer, der die angeforderten Informationen über das Token empfängt. Die struktur, die in diesen Puffer eingefügt wird, hängt vom Wert der TokenInformationClass ab, wie in der folgenden Tabelle dargestellt. Alle Strukturen müssen auf einer 32-Bit-Grenze ausgerichtet werden.

TokenInformationClass-Wert Effekt auf TokenInformation-Puffer
TokenDefaultDacl Der Puffer empfängt eine TOKEN_DEFAULT_DACL Struktur, die die Standard-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ätsstufe des Token angibt. Wenn das Zugriffstoken kein Identitätstoken ist, schlägt der Aufruf von NtQueryInformationToken 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 Standardgruppen-SID für neu erstellte Objekte enthält.
TokenPrivileges Der Puffer empfängt eine TOKEN_PRIVILEGES Struktur, die die Berechtigungen des Token enthält.
TokenSessionId Der Puffer erhält einen 32-Bit-Wert, der den Terminaldienste-Sitzungsbezeichner angibt, der dem Token zugeordnet ist. Wenn das Token der Terminal Server-Konsolensitzung zugeordnet ist, ist der Sitzungsbezeichner null. Ein Nichtzero-Sitzungsbezeichner gibt eine Terminaldienste-Clientsitzung an. In einer Nicht-Terminaldienste-Umgebung ist der Sitzungsbezeichner null.
TokenSource Der Puffer empfängt eine TOKEN_SOURCE Struktur, die die Quelle des Token enthält. TOKEN_QUERY_SOURCE Zugriff ist erforderlich, um diese Informationen abzurufen.
TokenStatistics Der Puffer empfängt eine TOKEN_STATISTICS Struktur mit verschiedenen Tokenstatistiken.
Tokentype Der Puffer empfängt einen TOKEN_TYPE Wert, der angibt, ob das Token ein primäres oder Identitätstoken ist.
TokenUser Der Puffer empfängt eine TOKEN_USER Struktur, die das Benutzerkonto des Token enthält.

[in] TokenInformationLength

Länge, in Bytes, des zugewiesenen TokenInformation-Puffers des Anrufers.

[out] ReturnLength

Zeiger auf eine Anrufer zugewiesene Variable, die die tatsächliche Länge in Bytes empfängt, von den im TokenInformation-Puffer zurückgegebenen Informationen. Wenn eine der folgenden Bedingungen wahr ist, werden keine Daten im TokenInformation-Puffer zurückgegeben:

  • Die Größe der angeforderten Tokeninformationsstruktur ist größer als TokenInformationLength. In diesem Fall erhält ReturnLength die tatsächliche Anzahl von Bytes, die zum Speichern der angeforderten Informationen erforderlich sind.

  • Der Wert von TokenInformationClass ist TokenDefaultDacl, und es gibt keine Standard-DACL für das Token eingerichtet. In diesem Fall erhält ReturnLength null.

ReturnLength kann nicht NULL sein. Weitere Informationen finden Sie unter Hinweise.

Rückgabewert

NtQueryInformationToken gibt STATUS_SUCCESS oder einen entsprechenden Fehlerstatus zurück. Mögliche Fehlerstatuscodes umfassen folgendes:

Rückgabecode Beschreibung
STATUS_ACCESS_DENIED TokenHandle hat keinen 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_ACCESS_VIOLATION ReturnLength war NULL oder war nicht beschreibbar, um die tatsächliche Länge der informationen zu erhalten, die von TokenInformation gezeigt wurden.
STATUS_INVALID_HANDLE TokenHandle war kein gültiger Handle.
STATUS_INVALID_INFO_CLASS TokenInformationClass war keine gültige Tokeninformationsklasse.
STATUS_OBJECT_TYPE_MISMATCH TokenHandle war kein Tokenhandle .

Bemerkungen

Die NtQueryInformationToken-Routine kann von einem Dateisystem- oder Dateisystemfiltertreiber verwendet werden, um die SID des Aufrufers zu ermitteln, der die Anforderung während der 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, der vom TokenInformation-Parameter angezeigt wird. Dieser zurückgegebene Puffer enthält eine SID_AND_ATTRIBUTES Struktur mit der Benutzer-SID.

Aufgrund der Art der Eigenschaften des Token (z. B. Tokenbenutzer, token primäre Gruppe, Berechtigungen usw.), wo der Inhalt auf jedem Token variieren kann, ist ReturnLength nicht optional; das heißt, es kann nicht NULL sein. Dies liegt daran, dass SID eine Variable-Länge-Struktur ist, während eine bestimmte Berechtigung in einem Token vorhanden sein kann, aber nicht in einem anderen (die Berechtigungsanzahl kann für jedes Token unterschiedlich sein). Es ist die Verantwortung des Aufrufers, zuerst die erforderliche Längengröße abzufragen, um Speicher zuzuweisen, um die angeforderten Tokeninformationen zu erfüllen, bevor die tatsächliche Abfrage ausgeführt wird. Das heißt, es ist auch die Verantwortung des Aufrufers, eine gültige ReturnLength-Variable bereitzustellen, die beschreibbar und nicht NULL ist. In einem NULL-Fallszenario löst die Funktion eine Zugriffsverletzungs ausnahme aus.

Weitere Informationen zur Sicherheits- und Zugriffssteuerung finden Sie in der Dokumentation zu diesen Themen im Windows SDK.

Hinweis

Wenn der Aufruf der NtQueryInformationToken-Funktion im Benutzermodus auftritt, sollten Sie den Namen "NtQueryInformationToken" anstelle von "ZwQueryInformationToken" verwenden.

Für Aufrufe von Kernelmodustreibern können sich die Nt Xxx- und ZwXxx-Versionen einer Windows Native System Services-Routine anders verhalten, wie sie Eingabeparameter behandeln und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und Zw Xxx-Versionen einer Routine finden Sie unter Using Nt and Zw Versions of the Native System Services Routines.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP
Zielplattform Universell
Header ntifs.h (einschließlich Ntifs.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI-Complianceregeln HwStorPortProhibitedDIs, PowerIrpDDis

Weitere Informationen

ACL

IRP_MJ_CREATE

SECURITY_IMPERSONATION_LEVEL

Sid

SID_AND_ATTRIBUTES

SeQueryInformationToken

TOKEN_DEFAULT_DACL

TOKEN_GROUPS

TOKEN_INFORMATION_CLASS

TOKEN_OWNER

TOKEN_PRIMARY_GROUP

TOKEN_PRIVILEGES

TOKEN_SOURCE

TOKEN_STATISTICS

TOKEN_TYPE

TOKEN_USER

ZwSetInformationToken