NtSetInformationToken - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTSEAPI_H
/**
* The NtSetInformationToken routine modifies information in a specified token. The calling process must have appropriate access rights to set the information.
*
* @param TokenHandle A handle to an existing access token which information is to be modified.
* @param TokenInformationClass A value from the TOKEN_INFORMATION_CLASS enumerated type identifying the type of information to be modified.
* @param TokenInformation Pointer to a caller-allocated buffer containing the information to be modified in the token.
* @param TokenInformationLength Length, in bytes, of the caller-allocated TokenInformation buffer.
* @return NTSTATUS Successful or errant status.
* @sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntsetinformationtoken
*/
NTSYSCALLAPI
NTSTATUS
NTAPI
NtSetInformationToken(
_In_ HANDLE TokenHandle,
_In_ TOKEN_INFORMATION_CLASS TokenInformationClass,
_In_reads_bytes_(TokenInformationLength) PVOID TokenInformation,
_In_ ULONG TokenInformationLength
);
View code on GitHub#ifndef _NTZWAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwSetInformationToken(
_In_ HANDLE TokenHandle,
_In_ TOKEN_INFORMATION_CLASS TokenInformationClass,
_In_reads_bytes_(TokenInformationLength) PVOID TokenInformation,
_In_ ULONG TokenInformationLength
);
View code on GitHub// ntifs.h
__kernel_entry NTSYSCALLAPI NTSTATUS NtSetInformationToken(
[in] HANDLE TokenHandle,
[in] TOKEN_INFORMATION_CLASS TokenInformationClass,
[in] PVOID TokenInformation,
[in] ULONG TokenInformationLength
);
View the official Windows Driver Kit DDI reference// ntifs.h
NTSYSAPI NTSTATUS ZwSetInformationToken(
[in] HANDLE TokenHandle,
[in] TOKEN_INFORMATION_CLASS TokenInformationClass,
[in] PVOID TokenInformation,
[in] ULONG TokenInformationLength
);
View the official Windows Driver Kit DDI referenceSets various information about the specified token. This function is partially documented in Windows Driver Kit here and here.
TokenHandle - a handle to the token. For most information classes, the handle must grant TOKEN_ADJUST_DEFAULT access.TokenInformationClass - the type of information to set.TokenInformation - a pointer to the buffer with the data specific to the request.TokenInformationLength - the size of the provided buffer in bytes.For the list of supported info classes and required token access, see TOKEN_INFORMATION_CLASS.
STATUS_TOKEN_ALREADY_IN_USE indicates that the specified type of information cannot be changed for a token that is currently used as a primary token for a process.Note that as opposed to NtQueryInformationToken, this function does not support token pseudo-handles.
The NtSetInformationToken routine modifies information in a specified token. The calling process must have appropriate access rights to set the information.
TokenHandle [in]Handle for an access token in which information is to be modified.
TokenInformationClass [in]A value from the TOKEN_INFORMATION_CLASS enumerated type identifying the type of information to be modified. 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 [in]Pointer to a caller-supplied buffer containing the information to be modified in the token. The structure of the information in 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 contains a TOKEN_DEFAULT_DACL structure specifying the default DACL for newly created objects. TOKEN_ADJUST_DEFAULT access is required to set this information. The buffer contents are not validated for structural correctness or consistency. |
| TokenGroups | Not a valid information class. This information is read-only. |
| TokenOwner | The buffer contains a TOKEN_OWNER structure specifying the default owner SID for newly created objects. TOKEN_ADJUST_DEFAULT access is required to set this information. The owner values that may be specified are restricted to the user and group IDs with an attribute indicating they can be assigned as the owner of objects. |
| TokenPrimaryGroup | The buffer contains a TOKEN_PRIMARY_GROUP structure specifying the default primary group SID for newly created objects. TOKEN_ADJUST_DEFAULT access is required to set this information. Must be one of the group IDs already in the token. |
| TokenPrivileges | Not a valid information class. This information is read-only. |
| TokenSource | Not a valid information class. This information is read-only. |
| TokenStatistics | Not a valid information class. This information is read-only. |
| TokenUser | Not a valid information class. This information is read-only. |
TokenInformationLength [in]Size, in bytes, of the structure passed in the TokenInformation buffer. Must be greater than or equal to the minimum value given in the following table.
| TokenInformationClass value | Minimum TokenInformationLength |
|---|---|
| TokenDefaultDacl | sizeof(TOKEN_DEFAULT_DACL) |
| TokenOwner | sizeof(TOKEN_OWNER) |
| TokenPrimaryGroup | sizeof(TOKEN_PRIMARY_GROUP) |
NtSetInformationToken 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_ALLOTTED_SPACE_EXCEEDED | The space allotted for storage of the default discretionary access control and the primary group ID is not large enough to accept the new value of one of these fields. |
| STATUS_INFO_LENGTH_MISMATCH | The value of TokenInformationLength was less than the required minimum. |
| STATUS_INSUFFICIENT_RESOURCES | The specified default owner's security information could not be captured. |
| STATUS_INVALID_HANDLE | TokenHandle was not a valid handle. |
| STATUS_INVALID_INFO_CLASS | TokenInformationClass was not a valid token information class. |
| STATUS_INVALID_OWNER | The caller cannot set the specified ID to be an owner (or default owner) of an object. |
| STATUS_INVALID_PRIMARY_GROUP | The caller cannot set the specified ID to be the primary group of an object. |
| STATUS_INVALID_SID | The specified default owner's security information was not valid. |
| STATUS_OBJECT_TYPE_MISMATCH | TokenHandle was not a token handle. |
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 NtSetInformationToken function occurs in kernel mode, you should use the name "ZwSetInformationToken" instead of "NtSetInformationToken".
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.
PsDereferenceImpersonationToken
Using Nt and Zw Versions of the Native System Services Routines
The ZwSetInformationToken routine modifies information in a specified token. The calling process must have appropriate access rights to set the information.
TokenHandle [in]Handle for an access token in which information is to be modified.
TokenInformationClass [in]A value from the TOKEN_INFORMATION_CLASS enumerated type identifying the type of information to be modified. 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 [in]Pointer to a caller-supplied buffer containing the information to be modified in the token. The structure of the information in 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 contains a TOKEN_DEFAULT_DACL structure specifying the default DACL for newly created objects. TOKEN_ADJUST_DEFAULT access is required to set this information. The buffer contents are not validated for structural correctness or consistency. |
| TokenGroups | Not a valid information class. This information is read-only. |
| TokenOwner | The buffer contains a TOKEN_OWNER structure specifying the default owner SID for newly created objects. TOKEN_ADJUST_DEFAULT access is required to set this information. The owner values that may be specified are restricted to the user and group IDs with an attribute indicating they can be assigned as the owner of objects. |
| TokenPrimaryGroup | The buffer contains a TOKEN_PRIMARY_GROUP structure specifying the default primary group SID for newly created objects. TOKEN_ADJUST_DEFAULT access is required to set this information. Must be one of the group IDs already in the token. |
| TokenPrivileges | Not a valid information class. This information is read-only. |
| TokenSource | Not a valid information class. This information is read-only. |
| TokenStatistics | Not a valid information class. This information is read-only. |
| TokenUser | Not a valid information class. This information is read-only. |
TokenInformationLength [in]Size, in bytes, of the structure passed in the TokenInformation buffer. Must be greater than or equal to the minimum value given in the following table.
| TokenInformationClass value | Minimum TokenInformationLength |
|---|---|
| TokenDefaultDacl | sizeof(TOKEN_DEFAULT_DACL) |
| TokenOwner | sizeof(TOKEN_OWNER) |
| TokenPrimaryGroup | sizeof(TOKEN_PRIMARY_GROUP) |
ZwSetInformationToken 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_ALLOTTED_SPACE_EXCEEDED | The space allotted for storage of the default discretionary access control and the primary group ID is not large enough to accept the new value of one of these fields. |
| STATUS_INFO_LENGTH_MISMATCH | The value of TokenInformationLength was less than the required minimum. |
| STATUS_INSUFFICIENT_RESOURCES | The specified default owner's security information could not be captured. |
| STATUS_INVALID_HANDLE | TokenHandle was not a valid handle. |
| STATUS_INVALID_INFO_CLASS | TokenInformationClass was not a valid token information class. |
| STATUS_INVALID_OWNER | The caller cannot set the specified ID to be an owner (or default owner) of an object. |
| STATUS_INVALID_PRIMARY_GROUP | The caller cannot set the specified ID to be the primary group of an object. |
| STATUS_INVALID_SID | The specified default owner's security information was not valid. |
| STATUS_OBJECT_TYPE_MISMATCH | TokenHandle was not a token handle. |
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 ZwSetInformationToken function occurs in user mode, you should use the name NtSetInformationToken" instead of "ZwSetInformationToken".
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.
PsDereferenceImpersonationToken
Using Nt and Zw Versions of the Native System Services Routines
This function is documented in Windows Driver Kit here and here.
Function NtSetInformationToken sets parameters of Token Objects. See also description of SetTokenInformation
in Win32 API SDK.
HANDLE to Token Object opened with TOKEN_ADJUST_DEFAULT access.
Information class described in TOKEN_INFORMATION_CLASS topic.
User's allocated buffer containing data to set to.
Length of TokenInformation buffer, in bytes.