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

Статья
03/08/2023

Подпрограмма 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. Используйте макрос NtCurrentThread , чтобы указать текущий поток.

[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 не был дескриптором потока.

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

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

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

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

Примечание

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

Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы собственных системных служб Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями процедуры NtXxx и ZwXxx см. в разделе Использование версий Nt и Zw для процедур собственных системных служб.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)