NtFilterToken - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTSEAPI_H
/**
* The NtFilterToken routine creates a new access token that is a restricted version of an existing access token.
*
* \param ExistingTokenHandle Handle to a primary or impersonation token. The token can also be a restricted token. This token must already be open for TOKEN_DUPLICATE access.
* \param Flags Specifies additional privilege options.
* \param SidsToDisable The deny-only SIDs to include in the restricted token. The system uses a deny-only SID to deny access to a securable object. The absence of a deny-only SID does not allow access.
* \param PrivilegesToDelete The privileges to delete in the restricted token. This parameter is optional and can be NULL.
* \param RestrictedSids The list of restricting SIDs for the new token. This parameter is optional and can be NULL.
* \param NewTokenHandle The new restricted token. The new token is the same type, primary or impersonation, as the existing token.
* \return NTSTATUS Successful or errant status.
* \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-sefiltertoken
*/
NTSYSCALLAPI
NTSTATUS
NTAPI
NtFilterToken(
_In_ HANDLE ExistingTokenHandle,
_In_ ULONG Flags,
_In_opt_ PTOKEN_GROUPS SidsToDisable,
_In_opt_ PTOKEN_PRIVILEGES PrivilegesToDelete,
_In_opt_ PTOKEN_GROUPS RestrictedSids,
_Out_ PHANDLE NewTokenHandle
);
View code on GitHub#ifndef _NTZWAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwFilterToken(
_In_ HANDLE ExistingTokenHandle,
_In_ ULONG Flags,
_In_opt_ PTOKEN_GROUPS SidsToDisable,
_In_opt_ PTOKEN_PRIVILEGES PrivilegesToDelete,
_In_opt_ PTOKEN_GROUPS RestrictedSids,
_Out_ PHANDLE NewTokenHandle
);
View code on GitHubCreates a restricted (filtered) copy of a token.
ExistingTokenHandle - a handle to an existing token. The handle must grant at least TOKEN_DUPLICATE access.Flags - a set of flags that control behavior of the function (see description below).SidsToDisable - an optional pointer to a collection of SIDs to be disabled and marked as use-for-deny-only in the new token.PrivilegesToDelete - an optional pointer to a collection of privileges to be removed from the new token.RestrictedSids - an optional pointer to a collection of (arbitrary) restricting SIDs that will be used to perform a secondary access check.NewTokenHandle - a pointer to a variable that receives a handle to the filtered token. The new handle grants the same access rights as the provided existing token handle.DISABLE_MAX_PRIVILEGE (0x01) - remove all privileges from the new token except for SeChangeNotifyPrivilege.SANDBOX_INERT (0x02) - allow the new token to bypass Software Restriction Policies and AppLocker rules. Note that the caller must have system-level privileges; otherwise, the function silently ignores this flag. To verify that the new token received the sandbox inert status, use NtQueryInformationToken with TokenSandBoxInert info class.LUA_TOKEN (0x04) - perform UAC-like filtration by disabling administrative-equivalent SIDs (see RtlIsElevatedRid) and privileges.WRITE_RESTRICTED (0x08) - use the secondary access check (against restricting SIDs) only when evaluating parts of GENERIC_WRITE access.To avoid retaining unused resources, call NtClose to close the returned handle when it is no longer required.
It is often convenient to use a full access handle for the existing (input) token because the system copies the granted access rights from the provided handle. Alternatively, you can reopen the new handle after filtration via NtDuplicateObject.
Note that this function does not support token pseudo-handles such as NtCurrentProcessToken. If you want to filter the current process/thread token, you need to open it first.