ZwQueryInformationToken function (ntifs.h)

  • Article

The ZwQueryInformationToken routine retrieves a specified type of information about an access token. The calling process must have appropriate access rights to obtain the information.

Syntax

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

Parameters

[in] TokenHandle

Handle for an access token from which information is to be retrieved. If TokenInformationClass is set to TokenSource, the handle must have TOKEN_QUERY_SOURCE access. For all other TokenInformationClass values, the handle must have TOKEN_QUERY access. For more information about access rights for access-token objects, see the Security section of the Windows SDK documentation.

[in] TokenInformationClass

A value from the TOKEN_INFORMATION_CLASS enumerated type identifying the type of information to be retrieved. The possible values for this parameter are listed in the TokenInformationClass Value column of the table shown in the description of the TokenInformation parameter.

[out] TokenInformation

Pointer to a caller-allocated buffer that receives the requested information about the token. The structure put into this buffer depends upon the value of TokenInformationClass, as shown in the following table. All structures must be aligned on a 32-bit boundary.

TokenInformationClass value Effect on TokenInformation buffer
TokenDefaultDacl The buffer receives a TOKEN_DEFAULT_DACL structure containing the default DACL for newly created objects.
TokenGroups The buffer receives a TOKEN_GROUPS structure containing the group accounts associated with the token.
TokenImpersonationLevel The buffer receives a SECURITY_IMPERSONATION_LEVEL value indicating the impersonation level of the token. If the access token is not an impersonation token, the call to ZwQueryInformationToken fails.
TokenOwner The buffer receives a TOKEN_OWNER structure containing the default owner SID for newly created objects.
TokenPrimaryGroup The buffer receives a TOKEN_PRIMARY_GROUP structure containing the default primary group SID for newly created objects.
TokenPrivileges The buffer receives a TOKEN_PRIVILEGES structure containing the token's privileges.
TokenSessionId The buffer receives a 32-bit value specifying the Terminal Services session identifier associated with the token. If the token is associated with the Terminal Server console session, the session identifier is zero. A nonzero session identifier indicates a Terminal Services client session. In a non-Terminal Services environment, the session identifier is zero.
TokenSource The buffer receives a TOKEN_SOURCE structure containing the source of the token. TOKEN_QUERY_SOURCE access is needed to retrieve this information.
TokenStatistics The buffer receives a TOKEN_STATISTICS structure containing various token statistics.
TokenType The buffer receives a TOKEN_TYPE value indicating whether the token is a primary or impersonation token.
TokenUser The buffer receives a TOKEN_USER structure containing the token's user account.

[in] TokenInformationLength

Length, in bytes, of the caller-allocated TokenInformation buffer.

[out] ReturnLength

Pointer to a caller-allocated variable that receives the actual length, in bytes, of the information returned in the TokenInformation buffer. If either of the following conditions is true, no data is returned in the TokenInformation buffer:

  • The size of the requested token information structure is greater than TokenInformationLength. In this case, ReturnLength receives the actual number of bytes needed to store the requested information.

  • The value of TokenInformationClass is TokenDefaultDacl, and there is no default DACL established for the token. In this case, ReturnLength receives zero.

Return value

ZwQueryInformationToken returns STATUS_SUCCESS or an appropriate error status. Possible error status codes include the following:

Return code Description
STATUS_ACCESS_DENIED TokenHandle did not have the required access.
STATUS_BUFFER_TOO_SMALL The size of the requested token information structure is greater than TokenInformationLength. The number of bytes required is returned in ReturnLength.
STATUS_INVALID_HANDLE TokenHandle was not a valid handle.
STATUS_INVALID_INFO_CLASS TokenInformationClass was not a valid token information class.
STATUS_OBJECT_TYPE_MISMATCH TokenHandle was not a token handle.

Remarks

The ZwQueryInformationToken routine can be used by a file system or file system filter driver to determine the SID of the caller that initiated the request during IRP_MJ_CREATE processing. If TokenUser is specified for the TokenInformationClass parameter passed to ZwQueryInformationToken, a TOKEN_USER structure is returned in the buffer pointed to by the TokenInformation parameter. This returned buffer contains an SID_AND_ATTRIBUTES structure with the user SID.

For more information about security and access control, see Windows security model for driver developers and the documentation on these topics in the Windows SDK.

Note

If the call to the ZwQueryInformationToken function occurs in user mode, you should use the name "NtQueryInformationToken" instead of "ZwQueryInformationToken".

For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

Requirements

Requirement Value
Minimum supported client Windows XP
Target Platform Universal
Header ntifs.h (include Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI compliance rules HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

See also

ACL

IRP_MJ_CREATE

SECURITY_IMPERSONATION_LEVEL

SID

SID_AND_ATTRIBUTES

SeQueryInformationToken

TOKEN_DEFAULT_DACL

TOKEN_GROUPS

TOKEN_INFORMATION_CLASS

TOKEN_OWNER

TOKEN_PRIMARY_GROUP

TOKEN_PRIVILEGES

TOKEN_SOURCE

TOKEN_STATISTICS

TOKEN_TYPE

TOKEN_USER

Using Nt and Zw Versions of the Native System Services Routines

ZwSetInformationToken