AdjustTokenPrivileges-Funktion (securitybaseapi.h)

Artikel
03/04/2024

Die Funktion AdjustTokenPrivileges aktiviert oder deaktiviert Berechtigungen im angegebenen Zugriffstoken. Das Aktivieren oder Deaktivieren von Berechtigungen in einem Zugriffstoken erfordert TOKEN_ADJUST_PRIVILEGES Zugriff.

Syntax

BOOL AdjustTokenPrivileges(
  [in]            HANDLE            TokenHandle,
  [in]            BOOL              DisableAllPrivileges,
  [in, optional]  PTOKEN_PRIVILEGES NewState,
  [in]            DWORD             BufferLength,
  [out, optional] PTOKEN_PRIVILEGES PreviousState,
  [out, optional] PDWORD            ReturnLength
);

Parameter

[in] TokenHandle

Ein Handle für das Zugriffstoken, das die zu ändernden Berechtigungen enthält. Das Handle muss TOKEN_ADJUST_PRIVILEGES Zugriff auf das Token haben. Wenn der PreviousState-Parameter nicht NULL ist, muss das Handle auch über TOKEN_QUERY Zugriff verfügen.

[in] DisableAllPrivileges

Gibt an, ob die Funktion alle Berechtigungen des Tokens deaktiviert. Wenn dieser Wert TRUE ist, deaktiviert die Funktion alle Berechtigungen und ignoriert den NewState-Parameter . Wenn es FALSE ist, ändert die Funktion Berechtigungen basierend auf den Informationen, auf die der NewState-Parameter verweist.

[in, optional] NewState

Ein Zeiger auf eine TOKEN_PRIVILEGES-Struktur , die ein Array von Berechtigungen und deren Attribute angibt. Wenn der DisableAllPrivileges-ParameterFALSE ist, aktiviert, deaktiviert oder entfernt die Funktion AdjustTokenPrivileges diese Berechtigungen für das Token. In der folgenden Tabelle wird die Aktion beschrieben, die von der Funktion AdjustTokenPrivileges basierend auf dem Berechtigungsattribut ausgeführt wird.

Wert	Bedeutung
SE_PRIVILEGE_ENABLED	Die Funktion aktiviert die Berechtigung.
SE_PRIVILEGE_REMOVED	Die Berechtigung wird aus der Liste der Berechtigungen im Token entfernt. Die anderen Berechtigungen in der Liste werden so neu sortiert, dass sie zusammenhängend bleiben. SE_PRIVILEGE_REMOVED ersetzt SE_PRIVILEGE_ENABLED. Da die Berechtigung aus dem Token entfernt wurde, führt der Versuch, die Berechtigung erneut zu aktivieren, dazu, dass die Warnung ERROR_NOT_ALL_ASSIGNED, als ob die Berechtigung nie vorhanden wäre. Wenn Sie versuchen, eine Berechtigung zu entfernen, die im Token nicht vorhanden ist, wird ERROR_NOT_ALL_ASSIGNED zurückgegeben. Berechtigungsprüfungen auf entfernte Berechtigungen führen zu STATUS_PRIVILEGE_NOT_HELD. Fehler bei der Berechtigungsprüfung erfolgt wie gewohnt. Das Entfernen der Berechtigung ist irreversibel, sodass der Name der entfernten Berechtigung nach einem Aufruf von AdjustTokenPrivileges nicht im PreviousState-Parameter enthalten ist. Windows XP mit SP1: Die Funktion kann keine Berechtigungen entfernen. Dieser Wert wird nicht unterstützt.
None	Die Funktion deaktiviert die Berechtigung.

Wert

Bedeutung

SE_PRIVILEGE_ENABLED

Die Funktion aktiviert die Berechtigung.

SE_PRIVILEGE_REMOVED

Die Berechtigung wird aus der Liste der Berechtigungen im Token entfernt. Die anderen Berechtigungen in der Liste werden so neu sortiert, dass sie zusammenhängend bleiben.

SE_PRIVILEGE_REMOVED ersetzt SE_PRIVILEGE_ENABLED.

Da die Berechtigung aus dem Token entfernt wurde, führt der Versuch, die Berechtigung erneut zu aktivieren, dazu, dass die Warnung ERROR_NOT_ALL_ASSIGNED, als ob die Berechtigung nie vorhanden wäre.

Wenn Sie versuchen, eine Berechtigung zu entfernen, die im Token nicht vorhanden ist, wird ERROR_NOT_ALL_ASSIGNED zurückgegeben.

Berechtigungsprüfungen auf entfernte Berechtigungen führen zu STATUS_PRIVILEGE_NOT_HELD. Fehler bei der Berechtigungsprüfung erfolgt wie gewohnt.

Das Entfernen der Berechtigung ist irreversibel, sodass der Name der entfernten Berechtigung nach einem Aufruf von AdjustTokenPrivileges nicht im PreviousState-Parameter enthalten ist.

Windows XP mit SP1: Die Funktion kann keine Berechtigungen entfernen. Dieser Wert wird nicht unterstützt.

None

Die Funktion deaktiviert die Berechtigung.

Wenn DisableAllPrivilegesTRUE ist, ignoriert die Funktion diesen Parameter.

[in] BufferLength

Gibt die Größe des Puffers in Bytes an, auf den der PreviousState-Parameter verweist. Dieser Parameter kann null sein, wenn der PreviousState-ParameterNULL ist.

[out, optional] PreviousState

Ein Zeiger auf einen Puffer, den die Funktion mit einer TOKEN_PRIVILEGES-Struktur füllt, die den vorherigen Status aller Berechtigungen enthält, die die Funktion ändert. Das heißt, wenn eine Berechtigung von dieser Funktion geändert wurde, sind die Berechtigung und ihr vorheriger Zustand in der TOKEN_PRIVILEGES Struktur enthalten, auf die von PreviousState verwiesen wird. Wenn das PrivilegeCount-Element von TOKEN_PRIVILEGES null ist, wurden von dieser Funktion keine Berechtigungen geändert. Dieser Parameter kann NULL sein.

Wenn Sie einen Puffer angeben, der zu klein ist, um die vollständige Liste der geänderten Berechtigungen zu erhalten, schlägt die Funktion fehl und passt keine Berechtigungen an. In diesem Fall legt die Funktion die Variable, auf die der ReturnLength-Parameter verweist, auf die Anzahl der Bytes fest, die erforderlich sind, um die vollständige Liste der geänderten Berechtigungen zu enthalten.

[out, optional] ReturnLength

Ein Zeiger auf eine Variable, die die erforderliche Größe des Puffers in Bytes empfängt, auf den der PreviousState-Parameter verweist. Dieser Parameter kann NULL sein, wenn PreviousStateNULL ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null. Um zu ermitteln, ob die Funktion alle angegebenen Berechtigungen angepasst hat, rufen Sie GetLastError auf, wodurch einer der folgenden Werte zurückgegeben wird, wenn die Funktion erfolgreich ist:

Rückgabecode	Beschreibung
ERROR_SUCCESS	Die Funktion hat alle angegebenen Berechtigungen angepasst.
ERROR_NOT_ALL_ASSIGNED	Das Token verfügt nicht über mindestens eine der im NewState-Parameter angegebenen Berechtigungen. Die Funktion kann mit diesem Fehlerwert erfolgreich sein, auch wenn keine Berechtigungen angepasst wurden. Der PreviousState-Parameter gibt die Berechtigungen an, die angepasst wurden.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die Funktion AdjustTokenPrivileges kann dem Zugriffstoken keine neuen Berechtigungen hinzufügen. Es kann nur die vorhandenen Berechtigungen des Tokens aktivieren oder deaktivieren. Um die Berechtigungen des Tokens zu bestimmen, rufen Sie die GetTokenInformation-Funktion auf.

Der NewState-Parameter kann Berechtigungen angeben, die das Token nicht besitzt, ohne dass die Funktion fehlschlägt. In diesem Fall passt die Funktion die Berechtigungen an, über die das Token verfügt, und ignoriert die anderen Berechtigungen, sodass die Funktion erfolgreich ist. Rufen Sie die GetLastError-Funktion auf, um zu ermitteln, ob die Funktion alle angegebenen Berechtigungen angepasst hat. Der PreviousState-Parameter gibt die Berechtigungen an, die angepasst wurden.

Der PreviousState-Parameter ruft eine TOKEN_PRIVILEGES-Struktur ab, die den ursprünglichen Zustand der angepassten Berechtigungen enthält. Um den ursprünglichen Zustand wiederherzustellen, übergeben Sie den PreviousState-Zeiger als NewState-Parameter in einem nachfolgenden Aufruf der AdjustTokenPrivileges-Funktion .

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Aktivieren und Deaktivieren von Berechtigungen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	securitybaseapi.h (einschließlich Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll