Fonction DuplicateTokenEx (securitybaseapi.h)

Article
08/25/2023

La fonction DuplicateTokenEx crée un 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

BOOL DuplicateTokenEx(
  [in]           HANDLE                       hExistingToken,
  [in]           DWORD                        dwDesiredAccess,
  [in, optional] LPSECURITY_ATTRIBUTES        lpTokenAttributes,
  [in]           SECURITY_IMPERSONATION_LEVEL ImpersonationLevel,
  [in]           TOKEN_TYPE                   TokenType,
  [out]          PHANDLE                      phNewToken
);

Paramètres

[in] hExistingToken

Handle à un jeton d’accès ouvert avec TOKEN_DUPLICATE accès.

[in] dwDesiredAccess

Spécifie les droits d’accès demandés pour le nouveau jeton. La fonction DuplicateTokenEx compare les droits d’accès demandés à 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. 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.

Pour obtenir la liste des droits d’accès pour les jetons d’accès, consultez Droits d’accès pour les objets Access-Token.

[in, optional] lpTokenAttributes

Pointeur vers une structure de SECURITY_ATTRIBUTES qui spécifie un descripteur de sécurité pour le nouveau jeton et détermine si les processus enfants peuvent hériter du jeton. Si lpTokenAttributes a la valeur NULL, le jeton obtient un descripteur de sécurité par défaut et le handle ne peut pas être hérité. Si le descripteur de sécurité contient une liste de contrôle d’accès système (SACL), le jeton obtient ACCESS_SYSTEM_SECURITY droit d’accès, même s’il n’a pas été demandé dans dwDesiredAccess.

Pour définir le propriétaire dans le descripteur de sécurité du nouveau jeton, le jeton de processus de l’appelant doit avoir le SE_RESTORE_NAME privilèges définis.

[in] ImpersonationLevel

Spécifie une valeur de l’énumération SECURITY_IMPERSONATION_LEVEL qui indique le niveau d’emprunt d’identité du nouveau jeton.

[in] TokenType

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

Valeur	Signification
TokenPrimary	Le nouveau jeton est un jeton principal que vous pouvez utiliser dans la fonction CreateProcessAsUser .
TokenImpersonation	Le nouveau jeton est un jeton d’emprunt d’identité.

[out] phNewToken

Pointeur vers une variable HANDLE qui reçoit le nouveau jeton.

Une fois que vous avez terminé d’utiliser le nouveau jeton, appelez la fonction CloseHandle pour fermer le handle de jeton.

Valeur retournée

Si la fonction réussit, la fonction retourne une valeur différente de zéro.

Si la fonction échoue, elle retourne zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Notes

La fonction DuplicateTokenEx vous permet de créer un jeton principal que vous pouvez utiliser dans la fonction CreateProcessAsUser . Cela permet à une application serveur qui emprunte l’identité d’un client de créer un processus qui a le contexte de sécurité du client. Notez que la fonction DuplicateToken peut créer uniquement des jetons d’emprunt d’identité, qui ne sont pas valides pour CreateProcessAsUser.

Voici un scénario classique pour l’utilisation de DuplicateTokenEx pour créer un jeton principal. Une application serveur crée un thread qui appelle l’une des fonctions d’emprunt d’identité, telles que ImpersonateNamedPipeClient, pour emprunter l’identité d’un client. Le thread d’emprunt d’identité appelle ensuite la fonction OpenThreadToken pour obtenir son propre jeton, qui est un jeton d’emprunt d’identité qui a le contexte de sécurité du client. Le thread spécifie ce jeton d’emprunt d’identité dans un appel à DuplicateTokenEx, en spécifiant l’indicateur TokenPrimary. La fonction DuplicateTokenEx crée un jeton principal qui a le contexte de sécurité du client.

Spécifications


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