Функция ZwQueryInformationToken (ntifs.h)
Подпрограмма 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) |
См. также раздел
Использование версий Nt и Zw собственных процедур системных служб