ZwSetInformationToken function (ntifs.h)

Article
02/22/2023

The ZwSetInformationToken routine modifies information in a specified token. The calling process must have appropriate access rights to set the information.

Syntax

NTSYSAPI NTSTATUS ZwSetInformationToken(
  [in] HANDLE                  TokenHandle,
  [in] TOKEN_INFORMATION_CLASS TokenInformationClass,
  [in] PVOID                   TokenInformation,
  [in] ULONG                   TokenInformationLength
);

Parameters

[in] TokenHandle

Handle for an access token in which information is to be modified.

[in] TokenInformationClass

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.

[in] TokenInformation

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.

[in] TokenInformationLength

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)

Return value

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.

Remarks

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 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 7
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)