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

Статья
12/21/2024

Программа 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 доступ. Дополнительные сведения о правах доступа для объектов маркера доступа см. в разделе "Безопасность" документации по пакету SDK для Windows.

[in] TokenInformationClass

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

[out] TokenInformation

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

Значение TokenInformationClass	Влияние на буфер TokenInformation
TokenDefaultDacl	Буфер получает структуру TOKEN_DEFAULT_DACL, содержащую DACL по умолчанию для вновь созданных объектов.
TokenGroups	Буфер получает TOKEN_GROUPS структуру, содержащую учетные записи группы, связанные с маркером.
TokenImpersonationLevel	Буфер получает значение SECURITY_IMPERSONATION_LEVEL, указывающее уровень олицетворения маркера. Если маркер доступа не является маркером олицетворения, вызов ZwQueryInformationToken завершается ошибкой.
токена	Буфер получает структуру TOKEN_OWNER, содержащую владельца по умолчанию sid для вновь созданных объектов.
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. Если одно из следующих условий имеет значение true, данные не возвращаются в буфере 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, структура TOKEN_USER возвращается в буфере, на который указывает параметр TokenInformation. Этот возвращенный буфер содержит структуру SID_AND_ATTRIBUTES с идентификатором безопасности пользователя.

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

Заметка

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

Для вызовов драйверов в режиме ядра 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)