NtQueryInformationToken 函数 （ntifs.h）
NtQueryInformationToken 例程检索有关访问令牌的指定类型信息。 调用过程必须具有适当的访问权限才能获取信息。
语法
__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationToken(
[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 值。 如果访问令牌不是模拟令牌，则调用 NtQueryInformationToken 失败。 |
| TokenOwner | 缓冲区接收一个 TOKEN_OWNER 结构，该结构包含新创建对象的默认所有者 SID。 |
| TokenPrimaryGroup | 缓冲区接收包含新创建对象的默认主组 SID 的 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 接收零。
ReturnLength 不能 NULL。 有关详细信息，请参阅“备注”。
返回值
NtQueryInformationToken 返回STATUS_SUCCESS或适当的错误状态。 可能的错误状态代码包括：
| 返回代码 | 描述 |
|---|---|
| STATUS_ACCESS_DENIED | TokenHandle 没有所需的访问权限。 |
| STATUS_BUFFER_TOO_SMALL | 请求的令牌信息结构的大小大于 TokenInformationLength。 ReturnLength中返回所需的字节数。 |
| STATUS_ACCESS_VIOLATION | ReturnLength 为 NULL 或不可写入，以便接收 TokenInformation所指向的信息的实际长度。 |
| STATUS_INVALID_HANDLE | TokenHandle 不是有效的句柄。 |
| STATUS_INVALID_INFO_CLASS | TokenInformationClass 不是有效的令牌信息类。 |
| STATUS_OBJECT_TYPE_MISMATCH | TokenHandle 不是令牌句柄。 |
言论
文件系统或文件系统筛选器驱动程序可以使用 NtQueryInformationToken 例程来确定在 IRP_MJ_CREATE 处理期间启动请求的调用方 SID。 如果为传递给 NtQueryInformationToken的 TokenInformationClass 参数指定了 TokenUser，则 TokenInformation 参数指向的缓冲区中返回 TOKEN_USER 结构。 此返回的缓冲区包含具有用户 SID的 SID_AND_ATTRIBUTES 结构。
由于令牌属性的性质（如令牌用户、令牌主组、特权等，其内容可能因每个令牌而异），ReturnLength 不可选;也就是说，它不能为 NULL。 这是因为 SID 是可变长度结构，而特定特权可以存在于令牌中，但不能存在于另一个令牌中（每个令牌的特权计数可能不同）。 调用方负责首先查询必要的所需长度大小，以便在执行实际查询之前分配内存以容纳请求的令牌信息。 也就是说，调用方有责任提供一个有效的 ReturnLength 变量，该变量是可写的，而不是 NULL。 在 NULL 案例方案中，该函数引发访问冲突异常。
有关安全和访问控制的详细信息，请参阅适用于驱动程序开发人员
注意
如果在用户模式下调用 NtQueryInformationToken 函数，则应使用名称“NtQueryInformationToken”而不是“ZwQueryInformationToken”。
对于内核模式驱动程序的调用，NtXxx 和 ZwXxx 版本的 Windows 本机系统服务例程的行为方式可能以不同的方式处理和解释输入参数。 有关 NtXxx 与 ZwXxx 例程之间的关系的详细信息，请参阅 使用 Nt 和 Zw 版本的本机系统服务例程。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows XP |
| 目标平台 | 普遍 |
| 标头 | ntifs.h （include Ntifs.h） |
| 库 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 符合性规则 | HwStorPortProhibitedDDI、PowerIrpDDis |