NtQueryInformationToken - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTSEAPI_H
/**
* The NtQueryInformationToken routine retrieves a specified type of information about an access token. The calling process must have appropriate access rights to obtain the information.
*
* @param TokenHandle A handle to an existing 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.
* @param TokenInformationClass A value from the TOKEN_INFORMATION_CLASS enumerated type identifying the type of information to be retrieved.
* @param TokenInformation Pointer to a caller-allocated buffer that receives the requested information about the token.
* @param TokenInformationLength Length, in bytes, of the caller-allocated TokenInformation buffer.
* @param ReturnLength Pointer to a caller-allocated variable that receives the actual length, in bytes, of the information returned in the TokenInformation buffer.
* @return NTSTATUS Successful or errant status.
* @sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntqueryinformationtoken
*/
NTSYSCALLAPI
NTSTATUS
NTAPI
NtQueryInformationToken(
_In_ HANDLE TokenHandle,
_In_ TOKEN_INFORMATION_CLASS TokenInformationClass,
_Out_writes_bytes_to_opt_(TokenInformationLength, *ReturnLength) PVOID TokenInformation,
_In_ ULONG TokenInformationLength,
_Out_ PULONG ReturnLength
);
View code on GitHub#ifndef _NTZWAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwQueryInformationToken(
_In_ HANDLE TokenHandle,
_In_ TOKEN_INFORMATION_CLASS TokenInformationClass,
_Out_writes_bytes_to_opt_(TokenInformationLength, *ReturnLength) PVOID TokenInformation,
_In_ ULONG TokenInformationLength,
_Out_ PULONG ReturnLength
);
View code on GitHub// ntifs.h
__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationToken(
[in] HANDLE TokenHandle,
[in] TOKEN_INFORMATION_CLASS TokenInformationClass,
[out] PVOID TokenInformation,
[in] ULONG TokenInformationLength,
[out] PULONG ReturnLength
);
View the official Windows Driver Kit DDI reference// ntifs.h
NTSYSAPI NTSTATUS ZwQueryInformationToken(
[in] HANDLE TokenHandle,
[in] TOKEN_INFORMATION_CLASS TokenInformationClass,
[out] PVOID TokenInformation,
[in] ULONG TokenInformationLength,
[out] PULONG ReturnLength
);
View the official Windows Driver Kit DDI referenceQueries various information about the specified token. This function is partially documented in Windows Driver Kit here and here.
TokenHandle - a handle to the token or one of the supported pseudo-handles (see below). For most information classes, the handle must grant TOKEN_QUERY access.TokenInformationClass - the type of information to retrieve.TokenInformation - a pointer to a user-allocated buffer that receives the requested information.TokenInformationLength - the size of the provided buffer in bytes.ReturnLength - an optional pointer to a variable that receives the number of bytes written when the function succeeds or the number of bytes requires when the buffer is too small.For the list of supported info classes and required token access, see TOKEN_INFORMATION_CLASS.
This function supports the following pseudo-handle values on Windows 8 and above:
NtCurrentProcessToken - performs the query on the primary token of the calling process.NtCurrentThreadToken - performs the query on the impersonation token of the calling thread. The function fails if the thread is not impersonating.NtCurrentThreadEffectiveToken - performs the query on the impersonation token of the calling thread, if present. Otherwise, the function uses the primary token of the calling process.STATUS_BUFFER_TOO_SMALL and STATUS_INFO_LENGTH_MISMATCH indicate that the requested information does not fit into the provided buffer.STATUS_CANT_OPEN_ANONYMOUS indicates that the caller attempted to query information about the current thread token while impersonating an anonymous token.The NtQueryInformationToken routine retrieves a specified type of information about an access token. The calling process must have appropriate access rights to obtain the information.
TokenHandle [in]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.
TokenInformationClass [in]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.
TokenInformation [out]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 NtQueryInformationToken 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. |
TokenInformationLength [in]Length, in bytes, of the caller-allocated TokenInformation buffer.
ReturnLength [out]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.
ReturnLength cannot be NULL. See Remarks for further information.
NtQueryInformationToken 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_ACCESS_VIOLATION | ReturnLength was NULL or was not writable in order to receive the actual length of the information pointed by TokenInformation. |
| 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. |
The NtQueryInformationToken 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 NtQueryInformationToken, 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.
Due to the nature of token's properties (such as token user, token primary group, privileges, etc, where their contents can vary on each token), ReturnLength is not optional; that is, it cannot be NULL. This is because SID is a variable-length structure whereas a specific privilege can exist in a token but not in another (the privilege count can be different for each token). It's the caller's responsibility to first query the necessary required length size in order to allocate memory to accommodate the requested token information before doing the actual query. That said, it is also the caller's responsibility to provide a valid ReturnLength variable that is writable and not NULL. On a NULL case scenario, the function raises an access violation exception.
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 NtQueryInformationToken function occurs in user mode, you should use the name "NtQueryInformationToken" instead of "ZwQueryInformationToken".
For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* 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 Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
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.
TokenHandle [in]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.
TokenInformationClass [in]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.
TokenInformation [out]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. |
TokenInformationLength [in]Length, in bytes, of the caller-allocated TokenInformation buffer.
ReturnLength [out]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.
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. |
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 Nt*Xxx* and Zw*Xxx* 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 Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
Using Nt and Zw Versions of the Native System Services Routines
This function is documented in Windows Driver Kit here and here.
Function NtQueryInformationToken receives information specified by information class from Token Object. See also Win32 API GetTokenInformation.
HANDLE to Token Object opened with TOKEN_QUERY access.
Information class described in TOKEN_INFORMATION_CLASS topic.
User's allocated buffer for output data. Format of output buffer depends on TokenInformationClass parameter.
Length of TokenInformation buffer, in bytes.
If output buffer is to small, value under this parameter receives required length.