Fonction DuplicateTokenEx (securitybaseapi.h)
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 |
|---|---|
|
Le nouveau jeton est un jeton principal que vous pouvez utiliser dans la fonction CreateProcessAsUser . |
|
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 |