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

Статья
08/25/2023

Функция DuplicateTokenEx создает новый маркер доступа , который дублирует существующий маркер. Эта функция может создать либо основной маркер , либо маркер олицетворения.

Синтаксис

BOOL DuplicateTokenEx(
  [in]           HANDLE                       hExistingToken,
  [in]           DWORD                        dwDesiredAccess,
  [in, optional] LPSECURITY_ATTRIBUTES        lpTokenAttributes,
  [in]           SECURITY_IMPERSONATION_LEVEL ImpersonationLevel,
  [in]           TOKEN_TYPE                   TokenType,
  [out]          PHANDLE                      phNewToken
);

Параметры

[in] hExistingToken

Дескриптор маркера доступа, открытого с TOKEN_DUPLICATE доступом.

[in] dwDesiredAccess

Указывает запрошенные права доступа для нового маркера. Функция DuplicateTokenEx сравнивает запрошенные права доступа со списком управления доступом (DACL) существующего маркера, чтобы определить, какие права предоставляются или запрещаются. Чтобы запросить те же права доступа, что и у существующего маркера, укажите ноль. Чтобы запросить все права доступа, действительные для вызывающей стороны, укажите MAXIMUM_ALLOWED.

Список прав доступа для маркеров доступа см. в разделе Права доступа для объектов Access-Token.

[in, optional] lpTokenAttributes

Указатель на структуру SECURITY_ATTRIBUTES , которая задает дескриптор безопасности для нового маркера и определяет, могут ли дочерние процессы наследовать маркер. Если lpTokenAttributes имеет значение NULL, маркер получает дескриптор безопасности по умолчанию и дескриптор не может быть унаследован. Если дескриптор безопасности содержит системный список управления доступом (SACL), маркер получает ACCESS_SYSTEM_SECURITY права доступа, даже если он не был запрошен в dwDesiredAccess.

Чтобы задать владельца в дескрипторове безопасности для нового маркера, маркер процесса вызывающего объекта должен иметь SE_RESTORE_NAME привилегии.

[in] ImpersonationLevel

Задает значение из перечисления SECURITY_IMPERSONATION_LEVEL , указывающее уровень олицетворения нового токена.

[in] TokenType

Задает одно из следующих значений перечисления TOKEN_TYPE .

Значение	Значение
TokenPrimary	Новый маркер является основным маркером , который можно использовать в функции CreateProcessAsUser .
TokenImpersonation	Новый маркер является токеном олицетворения.

[out] phNewToken

Указатель на переменную HANDLE , которая получает новый маркер.

Завершив использование нового маркера, вызовите функцию CloseHandle , чтобы закрыть дескриптор маркера.

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

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

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

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

Ниже приведен типичный сценарий использования DuplicateTokenEx для создания основного маркера. Серверное приложение создает поток, который вызывает одну из функций олицетворения, например ImpersonateNamedPipeClient, для олицетворения клиента. Затем поток олицетворения вызывает функцию OpenThreadToken для получения собственного маркера, который представляет собой токен олицетворения с контекстом безопасности клиента. Поток указывает этот токен олицетворения в вызове DuplicateTokenEx, указав флаг TokenPrimary. Функция DuplicateTokenEx создает основной маркер , имеющий контекст безопасности клиента.

Требования


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