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

Статья
03/15/2023

Функция CreateRestrictedToken создает новый маркер доступа , который является ограниченной версией существующего маркера доступа. Ограниченный маркер может иметь отключенные идентификаторы безопасности (SID), удаленные привилегии и список ограничивающих идентификаторов безопасности. Дополнительные сведения см. в разделе Ограниченные маркеры.

Синтаксис

BOOL CreateRestrictedToken(
  [in]           HANDLE               ExistingTokenHandle,
  [in]           DWORD                Flags,
  [in]           DWORD                DisableSidCount,
  [in, optional] PSID_AND_ATTRIBUTES  SidsToDisable,
  [in]           DWORD                DeletePrivilegeCount,
  [in, optional] PLUID_AND_ATTRIBUTES PrivilegesToDelete,
  [in]           DWORD                RestrictedSidCount,
  [in, optional] PSID_AND_ATTRIBUTES  SidsToRestrict,
  [out]          PHANDLE              NewTokenHandle
);

Параметры

[in] ExistingTokenHandle

Дескриптор первичного маркера или маркера олицетворения. Маркер также может быть ограниченным маркером. Дескриптор должен иметь TOKEN_DUPLICATE доступ к маркеру.

[in] Flags

Задает дополнительные параметры привилегий. Этот параметр может быть равен нулю или сочетанию следующих значений.

Значение	Значение
DISABLE_MAX_PRIVILEGE 0x1	Отключает все привилегии в новом маркере, кроме привилегии SeChangeNotifyPrivilege . Если это значение указано, параметры DeletePrivilegeCount и PrivilegesToDelete игнорируются.
SANDBOX_INERT 0x2	Если используется это значение, система не проверка правил AppLocker или не применяет политики ограничения программного обеспечения. Для AppLocker этот флаг отключает проверки для всех четырех коллекций правил: исполняемого файла, установщика Windows, скрипта и библиотеки DLL. При создании программы установки, которая должна запускать извлеченные библиотеки DLL во время установки, используйте флаг SAFER_TOKEN_MAKE_INERT в функции SaferComputeTokenFromLevel . Маркер можно запросить наличие этого флага с помощью GetTokenInformation. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: В системах с установленными KB2532445 вызывающий объект должен работать как LocalSystem или TrustedInstaller, иначе система игнорирует этот флаг. Дополнительные сведения см. в разделе "Вы можете обойти правила AppLocker с помощью макроса Office на компьютере под управлением Windows 7 или Windows Server 2008 R2" в базе знаний справки и поддержки по адресу http://support.microsoft.com/kb/2532445. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: AppLocker не поддерживается. AppLocker появился в Windows 7 и Windows Server 2008 R2.
LUA_TOKEN 0x4	Новый маркер является маркером LUA. Windows Server 2003 и Windows XP: Это значение не поддерживается.
WRITE_RESTRICTED 0x8	Новый маркер содержит ограничения идентификаторов безопасности, которые учитываются только при оценке доступа на запись. Windows XP с пакетом обновления 2 (SP2) и более поздних версий: Значение этой константы равно 0x4. Чтобы приложение было совместимо с Windows XP с операционными системами с пакетом обновления 2 (SP2) и более поздними версиями, приложение должно запрашивать операционную систему, вызвав функцию GetVersionEx , чтобы определить, какое значение следует использовать. Windows Server 2003 и Windows XP с пакетом обновления 1 (SP1) и более ранними версиями: Это значение не поддерживается.

[in] DisableSidCount

Указывает количество записей в массиве SidsToDisable .

[in, optional] SidsToDisable

Указатель на массив SID_AND_ATTRIBUTES структур, указывающих идентификаторы безопасности только для запрета в ограниченном маркере. Система использует идентификатор безопасности только для запрета, чтобы запретить доступ к защищаемому объекту. Отсутствие идентификатора безопасности только для запретов не разрешает доступ.

Отключение ИД безопасности включает SE_GROUP_USE_FOR_DENY_ONLY и отключает SE_GROUP_ENABLED и SE_GROUP_ENABLED_BY_DEFAULT. Все остальные атрибуты будут игнорироваться.

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

Функция игнорирует элемент Attributes структуры SID_AND_ATTRIBUTES .

Этот параметр может иметь значение NULL , если идентификаторы безопасности не должны быть отключены.

[in] DeletePrivilegeCount

Указывает количество записей в массиве PrivilegesToDelete .

[in, optional] PrivilegesToDelete

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

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

Функция игнорирует элементы Attributesструктур LUID_AND_ATTRIBUTES .

Этот параметр может иметь значение NULL , если вы не хотите удалять какие-либо привилегии.

Если вызывающая программа передает слишком много привилегий в этом массиве, CreateRestrictedToken возвращает ERROR_INVALID_PARAMETER.

[in] RestrictedSidCount

Указывает количество записей в массиве SidsToRestrict .

[in, optional] SidsToRestrict

Указатель на массив SID_AND_ATTRIBUTES структур, указывающих список ограничивающих идентификаторов безопасности для нового токена. Если существующий маркер является маркером ограниченного доступа, список ограничивающих идентификаторов безопасности для нового маркера является пересечением этого массива и списка ограничивающих идентификаторов безопасности для существующего маркера. Для удаления повторяющихся идентификаторов безопасности, помещенных в параметр SidsToRestrict, не выполняется проверка. Повторяющиеся идентификаторы безопасности позволяют ограниченному маркеру иметь избыточные сведения в списке ограничивающих идентификаторов безопасности.

Элемент Attributes структуры SID_AND_ATTRIBUTES должен быть равен нулю. Ограничение идентификаторов безопасности всегда включено для проверок доступа.

Этот параметр может иметь значение NULL , если вы не хотите указывать какие-либо ограничивающие идентификаторы безопасности.

[out] NewTokenHandle

Указатель на переменную, которая получает дескриптор нового ограниченного маркера. Этот дескриптор имеет те же права доступа, что и ExistingTokenHandle. Новый токен имеет тот же тип, основной или олицетворение, что и существующий маркер. Дескриптор, возвращенный в NewTokenHandle , можно дублировать.

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

Если функция выполняется успешно, возвращается ненулевое значение.

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

Примените атрибут только запрета к идентификаторам безопасности в маркере, чтобы их нельзя было использовать для доступа к защищенным объектам. Дополнительные сведения об атрибуте только запрета см. в разделе Атрибуты SID в маркере доступа.
Удалите привилегии из маркера.
Укажите список ограничивающих идентификаторов безопасности, который система использует при проверке доступа маркера к защищаемому объекту. Система выполняет две проверки доступа: одну с помощью включенных идентификаторов БЕЗОПАСНОСТИ маркера, а другую — с помощью списка ограничивающих идентификаторов безопасности. Доступ предоставляется только в том случае, если обе проверки доступа разрешают запрошенные права доступа.

Ограниченный маркер можно использовать в функции CreateProcessAsUser для создания процесса с ограниченными правами доступа и привилегиями. Если процесс вызывает CreateProcessAsUser с использованием ограниченной версии собственного маркера, вызывающей процедуре не требуется иметь права SE_ASSIGNPRIMARYTOKEN_NAME.

Ограниченный маркер можно использовать в функции ImpersonateLoggedOnUser .

Осторожностью Приложения, использующие ограниченные маркеры, должны запускать ограниченное приложение на рабочих столах, отличных от рабочего стола по умолчанию. Это необходимо для предотвращения атаки ограниченного приложения с помощью SendMessage или PostMessage на неограниченные приложения на рабочем столе по умолчанию. При необходимости переключайтесь между рабочими столами в целях приложения.

Требования

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