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

Статья
03/08/2023

Подпрограмма ZwQueryInformationToken извлекает сведения указанного типа о маркере доступа. Вызывающий процесс должен иметь соответствующие права доступа для получения информации.

Синтаксис

NTSYSAPI NTSTATUS ZwQueryInformationToken(
  [in]  HANDLE                  TokenHandle,
  [in]  TOKEN_INFORMATION_CLASS TokenInformationClass,
  [out] PVOID                   TokenInformation,
  [in]  ULONG                   TokenInformationLength,
  [out] PULONG                  ReturnLength
);

Параметры

[in] TokenHandle

Дескриптор маркера доступа, из которого требуется извлечь сведения. Если параметру TokenInformationClass присвоено значение TokenSource, дескриптор должен иметь доступ TOKEN_QUERY_SOURCE. Для всех остальных значений TokenInformationClass дескриптор должен иметь TOKEN_QUERY доступ. Дополнительные сведения о правах доступа для объектов маркеров доступа см. в разделе Безопасность документации по Windows SDK.

[in] TokenInformationClass

Значение из перечисленного типа TOKEN_INFORMATION_CLASS , определяющее тип извлекаемой информации. Возможные значения для этого параметра перечислены в столбце TokenInformationClass Value таблицы, показанной в описании параметра TokenInformation .

[out] TokenInformation

Указатель на буфер, выделенный вызывающим объектом, который получает запрошенные сведения о маркере. Структура, помещаемая в этот буфер, зависит от значения TokenInformationClass, как показано в следующей таблице. Все структуры должны быть выровнены по 32-разрядной границе.

Значение TokenInformationClass	Влияние на буфер TokenInformation
TokenDefaultDacl	Буфер получает TOKEN_DEFAULT_DACL структуру, содержащую daCL по умолчанию для вновь созданных объектов.
TokenGroups	Буфер получает TOKEN_GROUPS структуру, содержащую учетные записи группы, связанные с маркером.
TokenImpersonationLevel	Буфер получает значение SECURITY_IMPERSONATION_LEVEL , указывающее уровень олицетворения маркера. Если маркер доступа не является маркером олицетворения, вызов ZwQueryInformationToken завершается ошибкой .
TokenOwner	Буфер получает структуру TOKEN_OWNER , содержащую идентификатор безопасности владельца по умолчанию для вновь созданных объектов.
TokenPrimaryGroup	Буфер получает структуру TOKEN_PRIMARY_GROUP , содержащую идентификатор безопасности основной группы по умолчанию для вновь созданных объектов.
TokenPrivileges	Буфер получает TOKEN_PRIVILEGES структуру, содержащую привилегии маркера.
TokenSessionId	Буфер получает 32-разрядное значение, указывающее идентификатор сеанса служб терминалов, связанный с маркером. Если маркер связан с сеансом консоли сервера терминалов, идентификатор сеанса равен нулю. Ненулевой идентификатор сеанса указывает на сеанс клиента служб терминалов. В среде, отличной от служб терминалов, идентификатор сеанса равен нулю.
TokenSource	Буфер получает TOKEN_SOURCE структуру, содержащую источник маркера. TOKEN_QUERY_SOURCE для получения этих сведений требуется доступ.
TokenStatistics	Буфер получает структуру TOKEN_STATISTICS , содержащую различные статистические данные по маркерам.
TokenType	Буфер получает значение TOKEN_TYPE , указывающее, является ли маркер основным или маркером олицетворения.
TokenUser	Буфер получает TOKEN_USER структуру, содержащую учетную запись пользователя маркера.

[in] TokenInformationLength

Длина буфера TokenInformation , выделенного вызывающим объектом, в байтах.

[out] ReturnLength

Указатель на переменную, выделенную вызывающим объектом, которая получает фактическую длину (в байтах) сведений, возвращаемых в буфере TokenInformation . Если выполняется одно из следующих условий, данные в буфере TokenInformation не возвращаются:

Размер запрошенной структуры сведений о маркере больше, чем TokenInformationLength. В этом случае ReturnLength получает фактическое количество байтов, необходимых для хранения запрошенной информации.
Значение TokenInformationClass — TokenDefaultDacl, и для маркера по умолчанию не установлено daCL. В этом случае ReturnLength получает ноль.

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

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

Код возврата	Описание
STATUS_ACCESS_DENIED	У TokenHandle нет необходимого доступа.
STATUS_BUFFER_TOO_SMALL	Размер запрошенной структуры сведений о маркере больше, чем TokenInformationLength. Необходимое количество байтов возвращается в ReturnLength.
STATUS_INVALID_HANDLE	TokenHandle не был допустимым дескриптором.
STATUS_INVALID_INFO_CLASS	TokenInformationClass не является допустимым классом сведений о маркере.
STATUS_OBJECT_TYPE_MISMATCH	TokenHandle не был дескриптором маркера.

Подпрограмма ZwQueryInformationToken может использоваться файловой системой или драйвером фильтра файловой системы для определения идентификатора безопасности вызывающего объекта, инициировавшего запрос во время обработки IRP_MJ_CREATE . Если параметр TokenUser указан для параметра TokenInformationClass, передаваемого в ZwQueryInformationToken, в буфере, на который указывает параметр TokenInformation, возвращается структура TOKEN_USER. Возвращенный буфер содержит структуру SID_AND_ATTRIBUTES с идентификатором безопасности пользователя.

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

Примечание

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

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

Требования

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