CreateRestrictedToken, fonction (securitybaseapi.h)

Article
11/08/2024

La fonction CreateRestrictedToken crée un nouveau jeton d’accès qui est une version restreinte d’un jeton d’accès existant. Le jeton restreint peut avoir désactivé identificateurs de sécurité (SID), les privilèges supprimés et une liste de SID de restriction. 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 principal ou jeton 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 dans le 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 vérifie pas règles d' AppLocker ou applique stratégies de restriction logicielle. Pour appLocker, cet indicateur désactive 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é, l’appelant doit s’exécuter en tant que LocalSystem ou TrustedInstaller ou que 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. 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 restreints qui sont considérés 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 sp2 et versions ultérieures, 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 refuser 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 de refus uniquement s’appliquent à n’importe quelle combinaison de SID d’un jeton existant, y compris les SID d’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 les SID du tableau qui ne sont pas également trouvés dans le jeton existant.

La fonction ignore les attributs membre de la structure SID_AND_ATTRIBUTES.

Ce paramètre peut être 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 du tableau qui ne sont pas détenus par le jeton existant.

La fonction ignore les attributs membres des structures LUID_AND_ATTRIBUTES.

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

Si le programme appelant transmet 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 de restriction 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 de restriction pour le jeton existant. Aucune vérification 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 restreints.

Les attributs membre de la structure SID_AND_ATTRIBUTES doivent être zéro. La restriction des SID est toujours activée pour les vérifications d’accès.

Ce paramètre peut être NULL si vous ne souhaitez pas spécifier de SID de restriction.

[out] NewTokenHandle

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

Valeur de retour

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’erreur étendues, appelez GetLastError.

Remarques

La fonction CreateRestrictedToken peut restreindre le jeton de la manière suivante :

Appliquez l’attribut deny-only 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 deny-only, consultez attributs SID dans un jeton d’accès.
Supprimez privilèges du jeton.
Spécifiez la liste des SID de restriction, 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 : une à l’aide des SID activés par le jeton, et une autre à l’aide de la liste des SID de restriction. L’accès est accordé uniquement 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 restreints et de privilèges. 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.

Avertissement

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, pour des applications illimitées sur le bureau par défaut. Si nécessaire, basculez entre les bureaux à des fins de votre application.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	securitybaseapi.h (include Windows.h)
bibliothèque	Advapi32.lib
DLL	Advapi32.dll