ZwQueryInformationToken 函数 (ntifs.h)

项目
02/29/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访问权限。有关访问令牌对象访问权限的详细信息，请参阅 Windows SDK 文档的安全性部分。

[in] TokenInformationClass

TOKEN_INFORMATION_CLASS枚举类型的值，用于标识要检索的信息类型。此参数的可能值列在 TokenInformation 参数的说明中显示的表的 TokenInformationClass Value 列中。

[out] TokenInformation

指向调用方分配的缓冲区的指针，该缓冲区接收有关令牌的请求信息。放入此缓冲区中的结构取决于 TokenInformationClass 的值，如下表所示。所有结构都必须在 32 位边界上对齐。

TokenInformationClass 值	对 TokenInformation 缓冲区的影响
TokenDefaultDacl	缓冲区接收包含新创建对象的默认 DACL的TOKEN_DEFAULT_DACL结构。
TokenGroups	缓冲区接收包含与令牌关联的组帐户的TOKEN_GROUPS 结构。
TokenImpersonationLevel	缓冲区接收一个SECURITY_IMPERSONATION_LEVEL 值，该值指示令牌的模拟级别。如果访问令牌不是模拟令牌，则对 ZwQueryInformationToken 的调用将失败。
TokenOwner	缓冲区接收包含新创建对象的默认所有者 SID的TOKEN_OWNER结构。
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 接收零。

返回值

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处理期间发起请求的调用方 SID。如果为传递给 ZwQueryInformationToken 的 TokenInformationClass 参数指定 TokenUser，则会在 TokenInformation 参数指向的缓冲区中返回一个TOKEN_USER结构。此返回的缓冲区包含具有用户 SID的SID_AND_ATTRIBUTES结构。

有关安全性和访问控制的详细信息，请参阅面向驱动程序开发人员的 Windows 安全模型以及 Windows SDK 中有关这些主题的文档。

注意

如果在用户模式下调用 ZwQueryInformationToken 函数，则应使用名称“NtQueryInformationToken”而不是“ZwQueryInformationToken”。

对于来自内核模式驱动程序的调用，Windows 本机系统服务例程的 NtXxx 和 ZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。有关例程的 NtXxx 和 ZwXxx 版本之间的关系的详细信息，请参阅使用本机系统服务例程的 Nt 和 Zw 版本。

要求

要求	值
最低受支持的客户端	Windows XP
目标平台	通用
标头	ntifs.h (包括 Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 符合性规则	HwStorPortProhibitedDDI (storport) 、 PowerIrpDDis (wdm)