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

Функция 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

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

[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.

Комментарии

Функция CreateRestrictedToken может ограничить маркер следующими способами:

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

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

Требования

См. также раздел

Обзор контроль доступа

Базовые функции контроль доступа

CreateProcessAsUser

GetTokenInformation

ImpersonateLoggedOnUser

IsTokenRestricted

LUID_AND_ATTRIBUTES

SID_AND_ATTRIBUTES