Функция ZwOpenThreadTokenEx (ntifs.h)

Статья
12/21/2024

Подпрограмма ZwOpenThreadTokenEx открывает маркер доступа, связанный с потоком.

Синтаксис

NTSYSAPI NTSTATUS ZwOpenThreadTokenEx(
  [in]  HANDLE      ThreadHandle,
  [in]  ACCESS_MASK DesiredAccess,
  [in]  BOOLEAN     OpenAsSelf,
  [in]  ULONG       HandleAttributes,
  [out] PHANDLE     TokenHandle
);

Параметры

[in] ThreadHandle

Дескриптор потока, маркер доступа которого должен быть открыт. Дескриптор должен иметь доступ THREAD_QUERY_INFORMATION. Используйте макрос NtCurrentThreadThread, чтобы указать текущий поток.

[in] DesiredAccess

ACCESS_MASK структура, указывающая запрошенные типы доступа к маркеру доступа. Эти запрошенные типы доступа сравниваются со списком управления доступом маркера (DACL), чтобы определить, какие права доступа предоставляются или запрещены.

[in] OpenAsSelf

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

Если этот параметр FALSE, проверка доступа выполняется с помощью контекста безопасности для вызывающего потока. Если поток олицетворяет клиента, этот контекст безопасности может быть процессом клиента. Если этот параметр TRUE, проверка доступа выполняется с помощью контекста безопасности процесса для вызывающего потока.

[in] HandleAttributes

Атрибуты созданного дескриптора. В настоящее время поддерживается только OBJ_KERNEL_HANDLE. Если вызывающий объект не запущен в контексте системного процесса, он должен указать OBJ_KERNEL_HANDLE для этого параметра.

[out] TokenHandle

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

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

ZwOpenThreadTokenEx возвращает STATUS_SUCCESS или соответствующее состояние ошибки. Возможные коды состояния ошибок включают следующие:

Возвращаемый код	Описание
STATUS_ACCESS_DENIED	ThreadHandle не было THREAD_QUERY_INFORMATION доступа.
STATUS_CANT_OPEN_ANONYMOUS	Клиент запросил уровень олицетворения SecurityAnonymous. Однако анонимный маркер не может быть открыт. Дополнительные сведения см. в SECURITY_IMPERSONATION_LEVEL.
STATUS_INVALID_HANDLE	ThreadHandle не является допустимым дескриптором.
STATUS_INVALID_PARAMETER	Указанные HandleAttributes не включали OBJ_KERNEL_HANDLE.
STATUS_NO_TOKEN	Предпринята попытка открыть маркер, связанный с потоком, который в настоящее время не олицетворяет клиента.
STATUS_OBJECT_TYPE_MISMATCH	ThreadHandle не был дескриптором потока.

Замечания

ZwOpenThreadTokenEx открывает маркер доступа, связанный с потоком, и возвращает дескриптор для этого маркера.

Параметр OpenAsSelf позволяет серверу открывать маркер доступа для клиентского процесса, когда клиентский процесс указал уровень олицетворения SecurityIdentification для перечисленного типа SECURITY_IMPERSONATION_LEVEL. Без этого параметра вызывающий процесс не сможет открыть маркер доступа клиента с помощью контекста безопасности клиента, так как невозможно открыть объекты исполнительного уровня с помощью уровня олицетворения SecurityIdentification.

Любой дескриптор, полученный путем вызова ZwOpenThreadTokenEx, в конечном итоге должен быть освобожден путем вызова ZwClose.

Подпрограммы драйверов, выполняемые в контексте процесса, отличные от системного процесса, должны задать атрибут OBJ_KERNEL_HANDLE для параметра HandleAttributesZwOpenThreadTokenEx. Это ограничивает использование дескриптора, возвращаемого ZwOpenThreadTokenEx процессам, выполняемым в режиме ядра. В противном случае дескриптор может получить доступ к процессу, в контексте которого выполняется драйвер.

Дополнительные сведения о безопасности и управлении доступом см. в модели безопасности Windows для разработчиков драйверов и документации по этим разделам в пакете SDK для Windows.

Заметка

Если вызов функции ZwOpenThreadTokenEx происходит в пользовательском режиме, следует использовать имя "NtOpenThreadTokenEx" вместо "ZwOpenThreadTokenEx".

Для вызовов драйверов в режиме ядра NtXxx и ZwXxx версии подпрограммы Windows Native System Services могут вести себя по-разному в том, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между NtXxx и ZwXxx версиями подпрограммы см. в разделе Using Nt and Zw Versions of the Native System Services Routines.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP
целевая платформа	Всеобщий
заголовка	ntifs.h (include Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
правил соответствия DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)