ZwQueryInformationToken-Funktion (ntifs.h)

Artikel
02/26/2024

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)