Функция AdjustTokenPrivileges (securitybaseapi.h)

Статья
03/05/2024

Функция AdjustTokenPrivileges включает или отключает привилегии в указанном маркере доступа. Для включения или отключения привилегий в маркере доступа требуется доступ TOKEN_ADJUST_PRIVILEGES.

Синтаксис

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
);

Параметры

[in] TokenHandle

Дескриптор маркера доступа, который содержит привилегии, которые необходимо изменить. Дескриптор должен иметь TOKEN_ADJUST_PRIVILEGES доступ к маркеру. Если параметр PreviousState не имеет значение NULL, дескриптор также должен иметь доступ к TOKEN_QUERY.

[in] DisableAllPrivileges

Указывает, отключает ли функция все привилегии маркера. Если это значение равно TRUE, функция отключает все привилегии и игнорирует параметр NewState . Если имеет значение FALSE, функция изменяет привилегии на основе сведений, на которые указывает параметр NewState .

[in, optional] NewState

Указатель на структуру TOKEN_PRIVILEGES , указывающую массив привилегий и их атрибуты. Если параметр DisableAllPrivileges имеет значение FALSE, функция AdjustTokenPrivileges включает, отключает или удаляет эти привилегии для маркера. В следующей таблице описаны действия, выполняемые функцией AdjustTokenPrivileges на основе атрибута privilege.

Значение	Значение
SE_PRIVILEGE_ENABLED	Функция включает привилегию .
SE_PRIVILEGE_REMOVED	Привилегия удаляется из списка привилегий в маркере. Другие привилегии в списке переупорядочены так, чтобы они оставались непрерывными. SE_PRIVILEGE_REMOVED заменяет SE_PRIVILEGE_ENABLED. Так как привилегия была удалена из маркера, попытки повторно включить привилегию приводят к предупреждению ERROR_NOT_ALL_ASSIGNED, как если бы привилегия никогда не существовала. При попытке удалить привилегию, которая не существует в маркере, возвращается ERROR_NOT_ALL_ASSIGNED. Проверка привилегий для удаленных привилегий приводит к STATUS_PRIVILEGE_NOT_HELD. Сбой привилегий проверка аудит выполняется в обычном режиме. Удаление привилегии является необратимым, поэтому имя удаленной привилегии не включается в параметр PreviousState после вызова AdjustTokenPrivileges. Windows XP с пакетом обновления 1 (SP1): Функция не может удалить привилегии. Это значение не поддерживается.
None	Функция отключает привилегию.

Значение

SE_PRIVILEGE_ENABLED

Функция включает привилегию .

SE_PRIVILEGE_REMOVED

Привилегия удаляется из списка привилегий в маркере. Другие привилегии в списке переупорядочены так, чтобы они оставались непрерывными.

SE_PRIVILEGE_REMOVED заменяет SE_PRIVILEGE_ENABLED.

Так как привилегия была удалена из маркера, попытки повторно включить привилегию приводят к предупреждению ERROR_NOT_ALL_ASSIGNED, как если бы привилегия никогда не существовала.

При попытке удалить привилегию, которая не существует в маркере, возвращается ERROR_NOT_ALL_ASSIGNED.

Проверка привилегий для удаленных привилегий приводит к STATUS_PRIVILEGE_NOT_HELD. Сбой привилегий проверка аудит выполняется в обычном режиме.

Удаление привилегии является необратимым, поэтому имя удаленной привилегии не включается в параметр PreviousState после вызова AdjustTokenPrivileges.

Windows XP с пакетом обновления 1 (SP1): Функция не может удалить привилегии. Это значение не поддерживается.

None

Функция отключает привилегию.

Если параметр DisableAllPrivileges имеет значение TRUE, функция игнорирует этот параметр.

[in] BufferLength

Указывает размер (в байтах) буфера, на который указывает параметр PreviousState . Этот параметр может быть равен нулю, если параметр PreviousState имеет значение NULL.

[out, optional] PreviousState

Указатель на буфер, который функция заполняет структурой TOKEN_PRIVILEGES , содержащей предыдущее состояние всех привилегий, которые изменяет функция. То есть, если привилегия была изменена этой функцией, привилегия и ее предыдущее состояние содержатся в структуре TOKEN_PRIVILEGES , на которую ссылается PreviousState. Если элемент PrivilegeCountTOKEN_PRIVILEGES равен нулю, эта функция не изменила никаких привилегий. Этот параметр может принимать значение NULL.

Если указать буфер, который слишком мал для получения полного списка измененных привилегий, функция завершается ошибкой и не корректирует привилегии. В этом случае функция задает переменной, на которую указывает параметр ReturnLength , число байтов, необходимых для хранения полного списка измененных привилегий.

[out, optional] ReturnLength

Указатель на переменную, которая получает требуемый размер (в байтах) буфера, на который указывает параметр PreviousState . Этот параметр может иметь значение NULL, если Параметр PreviousState имеет значение NULL.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение. Чтобы определить, настроила ли функция все указанные привилегии, вызовите Метод GetLastError, который возвращает одно из следующих значений при успешном выполнении функции:

Код возврата	Описание
ERROR_SUCCESS	Функция корректирует все указанные привилегии.
ERROR_NOT_ALL_ASSIGNED	Маркер не имеет одного или нескольких привилегий, указанных в параметре NewState . Функция может быть успешно выполнена с этим значением ошибки, даже если привилегии не были скорректированы. Параметр PreviousState указывает права, которые были изменены.

Код возврата

Описание

ERROR_SUCCESS

Функция корректирует все указанные привилегии.

ERROR_NOT_ALL_ASSIGNED

Маркер не имеет одного или нескольких привилегий, указанных в параметре NewState . Функция может быть успешно выполнена с этим значением ошибки, даже если привилегии не были скорректированы. Параметр PreviousState указывает права, которые были изменены.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Функция AdjustTokenPrivileges не может добавить новые привилегии к маркеру доступа. Он может включать или отключать только существующие привилегии маркера. Чтобы определить привилегии маркера, вызовите функцию GetTokenInformation .

Параметр NewState может указать привилегии, которых нет у маркера, без сбоя функции. В этом случае функция корректирует привилегии, которые есть у маркера, и игнорирует другие привилегии, чтобы функция была успешной. Вызовите функцию GetLastError, чтобы определить, настроила ли функция все указанные привилегии. Параметр PreviousState указывает права, которые были изменены.

Параметр PreviousState извлекает структуру TOKEN_PRIVILEGES , содержащую исходное состояние скорректированных привилегий. Чтобы восстановить исходное состояние, передайте указатель PreviousState в качестве параметра NewState при последующем вызове функции AdjustTokenPrivileges .

Примеры

Пример использования этой функции см. в разделе Включение и отключение привилегий.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	securitybaseapi.h (включая Windows.h)
Библиотека	Advapi32.lib
DLL	Advapi32.dll