Fonction SeFilterToken (ntifs.h)

Article
02/26/2024

La routine SeFilterToken crée un jeton d’accès qui est une version restreinte d’un jeton d’accès existant.

Syntaxe

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

Paramètres

[in] ExistingToken

Pointeur vers un jeton principal ou d’emprunt d’identité. Le jeton peut également être un jeton restreint. Ce jeton doit déjà être ouvert pour TOKEN_DUPLICATE accès. Ce pointeur peut être obtenu à partir d’un handle de jeton existant en appelant ObReferenceObjectByHandle, en spécifiant TOKEN_DUPLICATE comme type DesiredAccess .

[in] Flags

Spécifie des options de privilèges supplémentaires. Ce paramètre peut être égal à zéro ou à une combinaison des valeurs suivantes.

Valeur	Signification
DISABLE_MAX_PRIVILEGE	Désactive tous les privilèges dans le nouveau jeton, à l’exception de SE_CHANGE_NOTIFY_PRIVILEGE. Si cette valeur est spécifiée, le paramètre PrivilegesToDelete est ignoré.
SANDBOX_INERT	Stocke l’indicateur TOKEN_SANDBOX_INERT dans le jeton.

[in, optional] SidsToDisable

Pointeur vers une structure de TOKEN_GROUPS contenant un tableau de structures SID_AND_ATTRIBUTES qui spécifient les SID de refus uniquement dans le jeton restreint. Le système utilise un SID de refus uniquement pour refuser l’accès à un objet sécurisable. L’absence d’un SID de refus uniquement n’autorise pas l’accès.

La désactivation d’un SID active SE_GROUP_USE_FOR_DENY_ONLY et désactive SE_GROUP_ENABLED et SE_GROUP_ENABLED_BY_DEFAULT. Tous les autres attributs sont ignorés.

Les attributs refus uniquement s’appliquent à toute combinaison de SID d’un jeton existant, y compris les SID utilisateur et les SID de groupe qui ont l’attribut SE_GROUP_MANDATORY. Pour obtenir les SID associés au jeton existant, appelez SeQueryInformationToken avec les indicateurs TokenUser et TokenGroups. SeFilterToken ignore tous les SID du tableau qui ne se trouvent pas également dans le jeton existant.

SeFilterToken ignore les membres Attributes des structures SID_AND_ATTRIBUTES.

Ce paramètre est facultatif et peut être NULL.

[in, optional] PrivilegesToDelete

Pointeur vers une structure TOKEN_PRIVILEGES contenant un tableau de structures LUID_AND_ATTRIBUTES qui spécifient les privilèges à supprimer dans le jeton restreint.

Pour obtenir les privilèges détenus par le jeton existant, appelez SeQueryInformationToken avec l’indicateur TokenPrivileges. SeFilterToken ignore tous les privilèges dans le tableau qui ne sont pas détenus par le jeton existant.

SeFilterToken ignore les membres Attributes des structures LUID_AND_ATTRIBUTES.

Ce paramètre est facultatif et peut être NULL.

[in, optional] RestrictedSids

Pointeur vers une structure de TOKEN_GROUPS contenant un tableau de structures SID_AND_ATTRIBUTES qui spécifient une liste de SID restrictifs pour le nouveau jeton. Si le jeton existant est un jeton restreint, la liste des SID de restriction pour le nouveau jeton est l’intersection de ce tableau et la liste des SID limitants pour le jeton existant.

Les membres Attributs des structures SID_AND_ATTRIBUTES doivent être de zéro. La restriction des SID est toujours activée pour les vérifications d’accès.

Ce paramètre est facultatif et peut être NULL.

FilteredToken

Pointeur vers une variable allouée par l’appelant qui reçoit l’adresse du nouveau jeton restreint. Le nouveau jeton est du même type, principal ou emprunt d’identité, que le jeton existant.

Valeur retournée

Si une ou plusieurs des valeurs de paramètre n’étaient pas valides, SeFilterToken retourne STATUS_INVALID_PARAMETER. (Cette valeur est retournée si le jeton cible n’est pas un jeton d’emprunt d’identité.) Sinon, SeFilterToken retourne STATUS_SUCCESS.

Remarques

SeFilterToken peut restreindre le jeton des manières suivantes :

Appliquez l’attribut refus uniquement aux SID dans le jeton afin qu’ils ne puissent pas être utilisés pour accéder aux objets sécurisés. Pour plus d’informations sur l’attribut de refus uniquement, consultez Attributs SID dans un jeton d’accès dans la documentation Microsoft Windows SDK.
Supprimez les privilèges du jeton.
Spécifiez une liste de SID restrictifs, que le système utilise lorsqu’il vérifie l’accès du jeton à un objet sécurisable. Le système effectue deux vérifications d’accès : l’une à l’aide des SID activés du jeton et l’autre à l’aide de la liste des SID restrictifs. L’accès n’est accordé que si les deux vérifications d’accès autorisent les droits d’accès demandés.

Le jeton restreint peut être utilisé avec SeCreateClientSecurity et SeImpersonateClientEx pour créer un processus disposant de droits d’accès et de privilèges restreints.

Pour plus d’informations sur la sécurité et le contrôle d’accès, consultez Modèle de sécurité Windows pour les développeurs de pilotes et la documentation sur ces rubriques dans le Kit de développement logiciel (SDK) Windows.

Lorsque le jeton retourné dans NewToken n’est plus nécessaire, libérez-le en appelant ObDereferenceObject.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP
Plateforme cible	Universal
En-tête	ntifs.h (inclure Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	< DISPATCH_LEVEL