Fonction DuplicateTokenEx (securitybaseapi.h)
La fonction DuplicateTokenEx crée un nouveau jeton d’accès qui duplique un jeton existant. Cette fonction peut créer un de jeton principal
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 vers un jeton d’accès ouvert avec un accès TOKEN_DUPLICATE.
[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 avec la liste de contrôle d’accès discrétionnaire du jeton existant (DACL) 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 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 est 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 jeu de privilèges SE_RESTORE_NAME.
[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.
Lorsque vous avez terminé d’utiliser le nouveau jeton, appelez la fonction CloseHandle pour fermer le handle de jeton.
Valeur de retour
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’erreur étendues, appelez GetLastError.
Remarques
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 d’utilisation 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 emprunt d’identitéNamedPipeClient, pour emprunter l’identité d’un client. L’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
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | securitybaseapi.h (include Windows.h) |
| bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |
Voir aussi
fonctions de contrôle d’accès de base