CreateRestrictedToken, fonction (securitybaseapi.h)

Article
08/25/2023

La fonction CreateRestrictedToken crée un jeton d’accès qui est une version restreinte d’un jeton d’accès existant. Le jeton restreint peut avoir des identificateurs de sécurité désactivés (SID), des privilèges supprimés et une liste de SID restrictifs. Pour plus d’informations, consultez Jetons restreints.

Syntaxe

BOOL CreateRestrictedToken(
  [in]           HANDLE               ExistingTokenHandle,
  [in]           DWORD                Flags,
  [in]           DWORD                DisableSidCount,
  [in, optional] PSID_AND_ATTRIBUTES  SidsToDisable,
  [in]           DWORD                DeletePrivilegeCount,
  [in, optional] PLUID_AND_ATTRIBUTES PrivilegesToDelete,
  [in]           DWORD                RestrictedSidCount,
  [in, optional] PSID_AND_ATTRIBUTES  SidsToRestrict,
  [out]          PHANDLE              NewTokenHandle
);

Paramètres

[in] ExistingTokenHandle

Handle vers un jeton principal ou d’emprunt d’identité. Le jeton peut également être un jeton restreint. Le handle doit avoir TOKEN_DUPLICATE accès au jeton.

[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 0x1	Désactive tous les privilèges du nouveau jeton, à l’exception du privilège SeChangeNotifyPrivilege . Si cette valeur est spécifiée, les paramètres DeletePrivilegeCount et PrivilegesToDelete sont ignorés.
SANDBOX_INERT 0x2	Si cette valeur est utilisée, le système ne case activée pas les règles AppLocker ou n’applique pas de stratégies de restriction logicielle. Pour AppLocker, cet indicateur désactive les vérifications pour les quatre collections de règles : Exécutable, Windows Installer, Script et DLL. Lors de la création d’un programme d’installation qui doit exécuter des DLL extraites pendant l’installation, utilisez l’indicateur SAFER_TOKEN_MAKE_INERT dans la fonction SaferComputeTokenFromLevel . Un jeton peut être interrogé pour l’existence de cet indicateur à l’aide de GetTokenInformation. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Sur les systèmes avec KB2532445 installés, l’appelant doit s’exécuter en tant que LocalSystem ou TrustedInstaller, ou le système ignore cet indicateur. Pour plus d’informations, consultez « Vous pouvez contourner les règles AppLocker à l’aide d’une macro Office sur un ordinateur exécutant Windows 7 ou Windows Server 2008 R2 » dans la Base de connaissances aide et support à l’adresse http://support.microsoft.com/kb/2532445. Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : AppLocker n’est pas pris en charge. AppLocker a été introduit dans Windows 7 et Windows Server 2008 R2.
LUA_TOKEN 0x4	Le nouveau jeton est un jeton LUA. Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.
WRITE_RESTRICTED 0x8	Le nouveau jeton contient des SID restrictifs qui sont pris en compte uniquement lors de l’évaluation de l’accès en écriture. Windows XP avec SP2 et versions ultérieures : La valeur de cette constante est 0x4. Pour qu’une application soit compatible avec Windows XP avec les systèmes d’exploitation SP2 et ultérieurs, l’application doit interroger le système d’exploitation en appelant la fonction GetVersionEx pour déterminer la valeur à utiliser. Windows Server 2003 et Windows XP avec SP1 et versions antérieures : Cette valeur n’est pas prise en charge.

[in] DisableSidCount

Spécifie le nombre d’entrées dans le tableau SidsToDisable .

[in, optional] SidsToDisable

Pointeur vers 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, utilisez la fonction GetTokenInformation avec les indicateurs TokenUser et TokenGroups. La fonction ignore tous les SID du tableau qui ne se trouvent pas également dans le jeton existant.

La fonction ignore le membre Attributes de la structure SID_AND_ATTRIBUTES .

Ce paramètre peut avoir la valeur NULL si aucun SID ne doit être désactivé.

[in] DeletePrivilegeCount

Spécifie le nombre d’entrées dans le tableau PrivilegesToDelete .

[in, optional] PrivilegesToDelete

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

La fonction GetTokenInformation peut être utilisée avec l’indicateur TokenPrivileges pour récupérer les privilèges détenus par le jeton existant. La fonction ignore tous les privilèges dans le tableau qui ne sont pas détenus par le jeton existant.

La fonction ignore les membres Attributes des structures LUID_AND_ATTRIBUTES .

Ce paramètre peut avoir la valeur NULL si vous ne souhaitez pas supprimer de privilèges.

Si le programme appelant passe trop de privilèges dans ce tableau, CreateRestrictedToken retourne ERROR_INVALID_PARAMETER.

[in] RestrictedSidCount

Spécifie le nombre d’entrées dans le tableau SidsToRestrict .

[in, optional] SidsToRestrict

Pointeur vers 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. Aucune case activée n’est effectuée pour supprimer les SID en double placés sur le paramètre SidsToRestrict. Les SID en double permettent à un jeton restreint d’avoir des informations redondantes dans la liste des SID restrictifs.

Le membre Attributes de la structure SID_AND_ATTRIBUTES doit être égal à zéro. La restriction des SID est toujours activée pour les vérifications d’accès.

Ce paramètre peut avoir la valeur NULL si vous ne souhaitez pas spécifier de SID restrictifs.

[out] NewTokenHandle

Pointeur vers une variable qui reçoit un handle vers le nouveau jeton restreint. Ce handle dispose des mêmes droits d’accès que ExistingTokenHandle. Le nouveau jeton est du même type, principal ou emprunt d’identité, que le jeton existant. Le handle retourné dans NewTokenHandle peut être dupliqué.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

La fonction CreateRestrictedToken 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.
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.

Vous pouvez utiliser le jeton restreint dans la fonction CreateProcessAsUser pour créer un processus disposant de droits d’accès et de privilèges restreints. Si un processus appelle CreateProcessAsUser à l’aide d’une version restreinte de son propre jeton, le processus appelant n’a pas besoin de disposer du privilège SE_ASSIGNPRIMARYTOKEN_NAME.

Vous pouvez utiliser le jeton restreint dans la fonction ImpersonateLoggedOnUser .

Attention Les applications qui utilisent des jetons restreints doivent exécuter l’application restreinte sur des bureaux autres que le bureau par défaut. Cela est nécessaire pour empêcher une attaque par une application restreinte, à l’aide de SendMessage ou PostMessage, vers des applications sans restriction sur le bureau par défaut. Si nécessaire, basculez entre les bureaux pour les besoins de votre application.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	securitybaseapi.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll