NtAdjustGroupsToken - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTSEAPI_H
/**
* The NtAdjustGroupsToken routine enables or disables groups in the specified access token.
*
* @param TokenHandle Handle to the token that contains the groups to be modified. The handle must have TOKEN_ADJUST_GROUPS access.
* @param ResetToDefault Specifies whether the function resets the groups to the default state. If this value is TRUE, the function resets all groups to their default state and ignores the NewState parameter.
* @param NewState A pointer to a TOKEN_GROUPS structure that specifies an array of groups and their attributes. If ResetToDefault is TRUE, the function ignores this parameter.
* @param BufferLength Specifies the size, in bytes, of the buffer pointed to by the PreviousState parameter. This parameter can be zero if the PreviousState parameter is NULL.
* @param PreviousState A pointer to a buffer that the function fills with a TOKEN_GROUPS structure that contains the previous state of any groups that the function modifies.
* @param ReturnLength A pointer to a variable that receives the required size, in bytes, of the buffer pointed to by the PreviousState parameter. This parameter can be NULL if PreviousState is NULL.
* @return NTSTATUS Successful or errant status.
* @sa https://learn.microsoft.com/en-us/windows/win32/api/securitybaseapi/nf-securitybaseapi-adjusttokengroups
*/
NTSYSCALLAPI
NTSTATUS
NTAPI
NtAdjustGroupsToken(
_In_ HANDLE TokenHandle,
_In_ BOOLEAN ResetToDefault,
_In_opt_ PTOKEN_GROUPS NewState,
_In_opt_ ULONG BufferLength,
_Out_writes_bytes_to_opt_(BufferLength, *ReturnLength) PTOKEN_GROUPS PreviousState,
_Out_opt_ PULONG ReturnLength
);
View code on GitHub#ifndef _NTZWAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwAdjustGroupsToken(
_In_ HANDLE TokenHandle,
_In_ BOOLEAN ResetToDefault,
_In_opt_ PTOKEN_GROUPS NewState,
_In_opt_ ULONG BufferLength,
_Out_writes_bytes_to_opt_(BufferLength, *ReturnLength) PTOKEN_GROUPS PreviousState,
_Out_opt_ PULONG ReturnLength
);
View code on GitHubEnables and disables groups in the token.
TokenHandle - a handle to the token. The handle must grant TOKEN_ADJUST_GROUPS access. Additionally, the handle must grant TOKEN_QUERY when the caller provides the PreviousState buffer.ResetToDefault - a boolean indicating if the function should reset group states to their defaults based on the presence of SE_GROUP_ENABLED_BY_DEFAULT flag.NewState - an optional pointer to a collection of group SIDs with their desired states, such as SE_GROUP_DISABLED (0) or SE_GROUP_ENABLED.BufferLength - the size of the PreviousState buffer in bytes.PreviousState - an optional pointer to a user-allocated buffer that receives the state of token groups prior to adjustment.ReturnLength - an optional pointer to a variable that receives the number of bytes written to the PreviousState buffer when the function succeeds or the number of bytes requires when the buffer is too small.STATUS_CANT_ENABLE_DENY_ONLY - the caller attempted to enable a group that has SE_GROUP_USE_FOR_DENY_ONLY flag set.STATUS_CANT_DISABLE_MANDATORY - the caller attempted to disable a group that has SE_GROUP_MANDATORY flag set.STATUS_NOT_ALL_ASSIGNED - this successful status indicates that not all of the requested groups were adjusted, such as when they are not present.STATUS_BUFFER_TOO_SMALL - the previous state data does not fit into the provided buffer.Groups are taken into account for granting access checks when they have SE_GROUP_ENABLED flag set. Groups are taken into account for denying access checks when they have either SE_GROUP_ENABLED or SE_GROUP_USE_FOR_DENY_ONLY flags set.
Note that this function does not support token pseudo-handles such as NtCurrentProcessToken. If you want to adjust the current process/thread token, you need to open it first.