NtSetInformationToken-Funktion (ntifs.h)

Artikel
03/08/2023

Die NtSetInformationToken-Routine ändert Informationen in einem angegebenen Token. Der aufrufende Prozess muss über geeignete Zugriffsrechte verfügen, um die Informationen festzulegen.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtSetInformationToken(
  [in] HANDLE                  TokenHandle,
  [in] TOKEN_INFORMATION_CLASS TokenInformationClass,
  [in] PVOID                   TokenInformation,
  [in] ULONG                   TokenInformationLength
);

Parameter

[in] TokenHandle

Handle für ein Zugriffstoken, in dem Informationen geändert werden sollen.

[in] TokenInformationClass

Ein Wert aus dem TOKEN_INFORMATION_CLASS aufgezählten Typ, der den Typ der zu ändernden 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.

[in] TokenInformation

Zeiger auf einen vom Aufrufer bereitgestellten Puffer, der die zu ändernden Informationen im Token enthält. Die Struktur der Informationen in diesem Puffer 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 enthält eine TOKEN_DEFAULT_DACL-Struktur , die die Standard-DACL für neu erstellte Objekte angibt. TOKEN_ADJUST_DEFAULT Zugriff ist erforderlich, um diese Informationen festzulegen. Die Pufferinhalte werden nicht auf strukturelle Richtigkeit oder Konsistenz überprüft.
TokenGruppen	Keine gültige Informationsklasse. Diese Informationen sind schreibgeschützt.
TokenOwner	Der Puffer enthält eine TOKEN_OWNER-Struktur , die die Standardbesitzer-SID für neu erstellte Objekte angibt. TOKEN_ADJUST_DEFAULT Zugriff ist erforderlich, um diese Informationen festzulegen. Die möglicherweise angegebenen Besitzerwerte sind auf die Benutzer- und Gruppen-IDs mit einem Attribut beschränkt, das angibt, dass sie als Besitzer von Objekten zugewiesen werden können.
TokenPrimaryGroup	Der Puffer enthält eine TOKEN_PRIMARY_GROUP-Struktur , die die Standard-primäre Gruppen-SID für neu erstellte Objekte angibt. TOKEN_ADJUST_DEFAULT Zugriff ist erforderlich, um diese Informationen festzulegen. Muss eine der Gruppen-IDs sein, die sich bereits im Token befinden.
TokenPrivileges	Keine gültige Informationsklasse. Diese Informationen sind schreibgeschützt.
TokenSource	Keine gültige Informationsklasse. Diese Informationen sind schreibgeschützt.
TokenStatistics	Keine gültige Informationsklasse. Diese Informationen sind schreibgeschützt.
TokenUser	Keine gültige Informationsklasse. Diese Informationen sind schreibgeschützt.

[in] TokenInformationLength

Die Größe der Struktur, die im Puffer TokenInformation übergeben wird, in Bytes. Muss größer oder gleich dem in der folgenden Tabelle angegebenen Mindestwert sein.

TokenInformationClass-Wert	Minimum TokenInformationLength
TokenDefaultDacl	sizeof(TOKEN_DEFAULT_DACL)
TokenOwner	sizeof(TOKEN_OWNER)
TokenPrimaryGroup	sizeof(TOKEN_PRIMARY_GROUP)

Rückgabewert

NtSetInformationToken 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_ALLOTTED_SPACE_EXCEEDED	Der für die Speicherung der standardmäßigen diskretionären Zugriffssteuerung zugewiesene Speicherplatz und die primäre Gruppen-ID ist nicht groß genug, um den neuen Wert eines dieser Felder zu akzeptieren.
STATUS_INFO_LENGTH_MISMATCH	Der Wert von TokenInformationLength war kleiner als der erforderliche Mindestwert.
STATUS_INSUFFICIENT_RESOURCES	Die Sicherheitsinformationen des angegebenen Standardbesitzers konnten nicht erfasst werden.
STATUS_INVALID_HANDLE	TokenHandle war kein gültiges Handle.
STATUS_INVALID_INFO_CLASS	TokenInformationClass war keine gültige Tokeninformationsklasse.
STATUS_INVALID_OWNER	Der Aufrufer kann die angegebene ID nicht als Besitzer (oder Standardbesitzer) eines Objekts festlegen.
STATUS_INVALID_PRIMARY_GROUP	Der Aufrufer kann die angegebene ID nicht als primäre Gruppe eines Objekts festlegen.
STATUS_INVALID_SID	Die Sicherheitsinformationen des angegebenen Standardbesitzers waren ungültig.
STATUS_OBJECT_TYPE_MISMATCH	TokenHandle war kein Tokenhandle.

Hinweise

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 NtSetInformationToken-Funktion im Kernelmodus erfolgt, sollten Sie den Namen "ZwSetInformationToken" anstelle von "NtSetInformationToken" 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 7
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis