SeFilterToken function (ntifs.h)
The SeFilterToken routine creates a new access token that is a restricted version of an existing access token.
Syntax
NTSTATUS SeFilterToken(
[in] PACCESS_TOKEN ExistingToken,
[in] ULONG Flags,
[in, optional] PTOKEN_GROUPS SidsToDisable,
[in, optional] PTOKEN_PRIVILEGES PrivilegesToDelete,
[in, optional] PTOKEN_GROUPS RestrictedSids,
PACCESS_TOKEN *FilteredToken
);
Parameters
[in] ExistingToken
Pointer to a primary or impersonation token. The token can also be a restricted token. This token must already be open for TOKEN_DUPLICATE access. This pointer can be obtained from an existing token handle by calling ObReferenceObjectByHandle, specifying TOKEN_DUPLICATE as the DesiredAccess type.
[in] Flags
Specifies additional privilege options. This parameter can be zero or a combination of the following values.
| Value | Meaning |
|---|---|
| DISABLE_MAX_PRIVILEGE | Disables all privileges in the new token except SE_CHANGE_NOTIFY_PRIVILEGE. If this value is specified, the PrivilegesToDelete parameter is ignored. |
| SANDBOX_INERT | Stores the TOKEN_SANDBOX_INERT flag in the token. |
[in, optional] SidsToDisable
Pointer to a TOKEN_GROUPS structure containing an array of SID_AND_ATTRIBUTES structures that specify the deny-only SIDs 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.
Disabling a SID turns on SE_GROUP_USE_FOR_DENY_ONLY and turns off SE_GROUP_ENABLED and SE_GROUP_ENABLED_BY_DEFAULT. All other attributes are ignored.
Deny-only attributes apply to any combination of an existing token's SIDs, including the user SID and group SIDs that have the SE_GROUP_MANDATORY attribute. To get the SIDs associated with the existing token, call SeQueryInformationToken with the TokenUser and TokenGroups flags. SeFilterToken ignores any SIDs in the array that are not also found in the existing token.
SeFilterToken ignores the Attributes members of the SID_AND_ATTRIBUTES structures.
This parameter is optional and can be NULL.
[in, optional] PrivilegesToDelete
Pointer to a TOKEN_PRIVILEGES structure containing an array of LUID_AND_ATTRIBUTES structures that specify the privileges to delete in the restricted token.
To get the privileges held by the existing token, call SeQueryInformationToken with the TokenPrivileges flag. SeFilterToken ignores any privileges in the array that are not held by the existing token.
SeFilterToken ignores the Attributes members of the LUID_AND_ATTRIBUTES structures.
This parameter is optional and can be NULL.
[in, optional] RestrictedSids
Pointer to a TOKEN_GROUPS structure containing an array of SID_AND_ATTRIBUTES structures that specify a list of restricting SIDs for the new token. If the existing token is a restricted token, the list of restricting SIDs for the new token is the intersection of this array and the list of restricting SIDs for the existing token.
The Attributes members of the SID_AND_ATTRIBUTES structures must be zero. Restricting SIDs are always enabled for access checks.
This parameter is optional and can be NULL.
FilteredToken
Pointer to a caller-allocated variable that receives the address of the new restricted token. The new token is the same type, primary or impersonation, as the existing token.
Return value
If one or more of the parameter values were invalid, SeFilterToken returns STATUS_INVALID_PARAMETER. (This value is returned if the target token is not an impersonation token.) Otherwise, SeFilterToken returns STATUS_SUCCESS.
Remarks
SeFilterToken can restrict the token in the following ways:
Apply the deny-only attribute to SIDs in the token so they cannot be used to access secured objects. For more information about the deny-only attribute, see SID Attributes in an Access Token in the Microsoft Windows SDK documentation.
Remove privileges from the token.
Specify a list of restricting SIDs, which the system uses when it checks the token's access to a securable object. The system performs two access checks: one using the token's enabled SIDs, and another using the list of restricting SIDs. Access is granted only if both access checks allow the requested access rights.
The restricted token can be used together with SeCreateClientSecurity and SeImpersonateClientEx to create a process that has restricted access rights and privileges.
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.
When the token returned in NewToken is no longer needed, free it by calling ObDereferenceObject.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP |
| Target Platform | Universal |
| Header | ntifs.h (include Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL |