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

Статья
11/20/2024

Функция 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 Rights for Access-Token Objects.

[in, optional] lpTokenAttributes

Указатель на структуру SECURITY_ATTRIBUTES, которая задает дескриптор безопасности для нового маркера и определяет, могут ли дочерние процессы наследовать маркер. Если lpTokenAttributesNULL, маркер получает дескриптор безопасности по умолчанию и дескриптор безопасности не может наследоваться. Если дескриптор безопасности содержит список системного управления доступом (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]
целевая платформа	Виндоус
заголовка	securitybaseapi.h (включая Windows.h)
библиотеки	Advapi32.lib
DLL	Advapi32.dll