ZwDuplicateToken, fonction (ntifs.h)

La fonction ZwDuplicateToken crée un handle pour un nouveau jeton d’accès qui duplique un jeton existant. Cette fonction peut créer un jeton principal ou un jeton d’emprunt d’identité.

Syntaxe

NTSYSAPI NTSTATUS ZwDuplicateToken(
  [in]  HANDLE             ExistingTokenHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  BOOLEAN            EffectiveOnly,
  [in]  TOKEN_TYPE         TokenType,
  [out] PHANDLE            NewTokenHandle
);

Paramètres

[in] ExistingTokenHandle

Handle d’un jeton d’accès existant qui a été ouvert avec le droit d’accès TOKEN_DUPLICATE. Ce paramètre est obligatoire et ne peut pas être NULL.

[in] DesiredAccess

Masque de bits qui spécifie les droits d’accès demandés pour le nouveau jeton. ZwDuplicateToken compare les droits d’accès demandés avec la liste de contrôle d’accès discrétionnaire (DACL) du jeton existant pour déterminer quels droits sont accordés ou refusés au nouveau jeton. Pour demander les mêmes droits d’accès que le jeton existant, spécifiez zéro. Pour demander tous les droits d’accès valides pour l’appelant, spécifiez MAXIMUM_ALLOWED. Ce paramètre est facultatif et peut être égal à zéro, MAXIMUM_ALLOWED ou une combinaison de bits OU d’une ou plusieurs des valeurs suivantes :

Pour plus d’informations, consultez Droits d’accès pour les objets Access-Token dans le SDK Windows. Notez que les jetons d’accès ne prennent pas en charge le droit SYNCHRONIZE.

[in] ObjectAttributes

Pointeur vers une structure OBJECT_ATTRIBUTES qui décrit les propriétés demandées pour le nouveau jeton. Le paramètre ObjectAttributes est facultatif et peut être NULL. Si le paramètre ObjectAttributes a la valeur NULL ou si le membre SecurityDescriptor de la structure pointée par le paramètre ObjectAttributes est NULL, le nouveau jeton reçoit un descripteur de sécurité par défaut et le nouveau handle de jeton ne peut pas être hérité. Dans ce cas, ce descripteur de sécurité par défaut est créé à partir du groupe d’utilisateurs, du groupe principal et des informations DACL stockées dans le jeton de l’appelant.

Lorsque le paramètre TokenType est défini sur TokenImpersonation :

• Le paramètre ObjectAttributes peut être utilisé pour spécifier le niveau d’emprunt d’identité du nouveau jeton. Pour ce faire, définissez ObjectAttributes-SecurityQualityOfService.ImpersonationLevel >sur une valeur d’énumération SECURITY_IMPERSONATION_LEVEL appropriée. Pour plus d’informations, consultez SECURITY_QUALITY_OF_SERVICE.

• Si le jeton existant est un jeton d’emprunt d’identité et que le paramètre ObjectAttributes ne fournit aucune information d’emprunt d’identité, le niveau d’emprunt d’identité du nouveau jeton est défini sur le niveau d’emprunt d’identité du jeton existant.

• Si le jeton existant est un jeton principal et qu’aucune information de niveau d’emprunt d’identité n’est fournie, le nouveau jeton d’emprunt d’identité aura un niveau d’emprunt d’identité SECURITY_IMPERSONATION_LEVEL.

[in] EffectiveOnly

Valeur booléenne qui indique si la totalité du jeton existant doit être dupliquée dans le nouveau jeton ou uniquement dans la partie effective (actuellement activée) du jeton. Si la valeur est TRUE, seules les parties actuellement activées du jeton source sont dupliquées. Si la valeur est FALSE, la totalité du jeton existant est dupliquée. Cela permet à l’appelant d’un sous-système protégé de limiter les groupes et privilèges facultatifs mis à la disposition du sous-système protégé. Par exemple, si EffectiveOnly a la valeur TRUE, l’appelant peut dupliquer un jeton, mais supprimer le groupe Administrateurs et le droit SeTcbPrivilege. Le jeton résultant peut ensuite être passé à un processus enfant (CreateProcessAsUser), ce qui limiterait ce que le processus enfant peut faire. Ce paramètre est obligatoire.

[in] TokenType

Spécifie l’une des valeurs suivantes de l’énumération TOKEN_TYPE .

Le paramètre TokenType est obligatoire et ne peut pas être NULL.

[out] NewTokenHandle

Pointeur vers une variable allouée par l’appelant, de type HANDLE, qui reçoit un handle vers le nouveau jeton. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

Valeur retournée

ZwDuplicateToken retourne STATUS_SUCCESS si l’appel réussit. Les codes de retour d’erreur possibles sont les suivants :

Remarques

Si aucune information de niveau d’emprunt d’identité n’a été fournie par le paramètre ObjectAttributes , le niveau d’emprunt d’identité du jeton existant est utilisé pour le nouveau jeton.

En ce qui concerne la structure pointée vers le paramètre ObjectAttributes facultatif, le membre SecurityQualityOfService de OBJECT_ATTRIBUTES pointe vers une structure de type SECURITY_QUALITY_OF_SERVICE. Consultez SECURITY_QUALITY_OF_SERVICE pour plus d’informations sur les membres de cette structure.

Le membre SecurityQualityOfService doit être défini après l’appel de la macro InitializeObjectAttributes , car InitializeObjectAttributes définit actuellement SecurityQualityOfService sur NULL.

Pour plus d’informations sur l’analogue en mode utilisateur de ZwDuplicateToken, consultez DuplicateTokenEx.

Lorsque vous avez terminé d’utiliser le nouveau jeton, appelez la fonction ZwClose pour fermer le handle de jeton.

Si l’appel à la fonction ZwDuplicateToken se produit en mode utilisateur, vous devez utiliser le nom « NtDuplicateToken » au lieu de « ZwDuplicateToken ».

Pour les appels à partir de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Utilisation des versions Nt et Zw des routines des services système natifs.

Configuration requise

Voir aussi

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

SECURITY_IMPERSONATION_LEVEL