NtSetInformationToken function (ntifs.h)

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

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtSetInformationToken(
  [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

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.

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 NtSetInformationToken function occurs in kernel mode, you should use the name "ZwSetInformationToken" instead of "NtSetInformationToken".

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, PowerIrpDDis

See also

NtQueryInformationToken

PsDereferenceImpersonationToken

PsDereferencePrimaryToken

SECURITY_IMPERSONATION_LEVEL

SID

SeQueryAuthenticationIdToken

SeQuerySubjectContextToken

SeTokenIsAdmin

SeTokenIsRestricted

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