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 :
| Valeur | Signification |
|---|---|
| Suppression | Requis pour supprimer l’objet. |
| READ_CONTROL | Requis pour lire les informations DACL et de propriété de l’objet. Pour accéder à la liste de contrôle d’accès système (SACL), consultez ACCESS_SYSTEM_SECURITY plus loin dans ce tableau. |
| WRITE_DAC | Requis pour modifier les informations DACL pour l’objet . |
| WRITE_OWNER | Requis pour modifier les informations de propriété dans le descripteur de sécurité (SECURITY_DESCRIPTOR) de l’objet. |
| ACCESS_SYSTEM_SECURITY | Requis pour obtenir ou définir la SACL dans l’ACL d’un objet. Le système d’exploitation accorde ce droit au nouveau jeton uniquement si le privilège SE_SECURITY_NAME est activé dans le jeton d’accès du thread appelant. |
| STANDARD_RIGHTS_READ | Actuellement défini pour être égal à READ_CONTROL. |
| STANDARD_RIGHTS_WRITE | Actuellement défini pour être égal à READ_CONTROL. |
| STANDARD_RIGHTS_EXECUTE | Actuellement défini pour être égal à READ_CONTROL. |
| STANDARD_RIGHTS_REQUIRED | Combine delete, READ_CONTROL, WRITE_DAC et accès WRITE_OWNER. |
| STANDARD_RIGHTS_ALL | Combine l’accès DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER et SYNCHRONIZE. Toutefois, la valeur SYNCHRONIZE ne s’applique pas aux objets de jeton. Ainsi, STANDARD_RIGHTS_ALL a un équivalent fonctionnel de STANDARD_RIGHTS_REQUIRED. |
| TOKEN_ADJUST_DEFAULT | Requis pour modifier le propriétaire par défaut, le groupe principal ou la liste DACL d’un jeton d’accès. |
| TOKEN_ADJUST_GROUPS | Requis pour ajuster les attributs des groupes dans un jeton d’accès. |
| TOKEN_ADJUST_PRIVILEGES | Requis pour activer ou désactiver les privilèges dans un jeton d’accès. |
| TOKEN_ADJUST_SESSIONID | Requis pour ajuster l’ID de session (SID) d’un jeton d’accès. Le système d’exploitation accorde ce droit au nouveau jeton uniquement si le privilège SE_TCB_NAME est activé dans le jeton d’accès du thread appelant. |
| TOKEN_ASSIGN_PRIMARY | Requis pour attacher un jeton principal à un processus. Le système d’exploitation accorde ce droit au nouveau jeton uniquement si le privilège SE_ASSIGNPRIMARYTOKEN_NAME est activé dans le jeton d’accès du thread appelant. |
| TOKEN_DUPLICATE | Obligatoire pour dupliquer un jeton d’accès. Notez que le jeton ExistingTokenHandle donné doit contenir ce droit pour pouvoir utiliser correctement cette routine. |
| TOKEN_EXECUTE | Combine STANDARD_RIGHTS_EXECUTE et TOKEN_IMPERSONATE. |
| TOKEN_IMPERSONATE | Requis pour attacher un jeton d’accès d’emprunt d’identité à un processus. |
| TOKEN_QUERY | Requis pour interroger un jeton d’accès. |
| TOKEN_QUERY_SOURCE | Requis pour interroger la source d’un jeton d’accès. |
| TOKEN_READ | Combine STANDARD_RIGHTS_READ et TOKEN_QUERY. |
| TOKEN_WRITE | Combine STANDARD_RIGHTS_WRITE, TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS et TOKEN_ADJUST_DEFAULT. |
| TOKEN_ALL_ACCESS | Combine toutes les autorisations d’accès au jeton possibles pour un jeton. |
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 .
| Valeur | Signification |
|---|---|
| TokenPrimary | Le nouveau jeton est un jeton principal. Si le jeton existant est un jeton d’emprunt d’identité, le jeton d’emprunt d’identité existant doit avoir un niveau d’emprunt d’identité (tel que fourni par le paramètre ObjectAttributes ) de SecurityImpersonation ou SecurityDelegation. Sinon, ZwDuplicateToken retourne STATUS_BAD_IMPERSONATION_LEVEL est retourné. |
| TokenImpersonation | Le nouveau jeton est un jeton d’emprunt d’identité. Si le jeton existant est un jeton d’emprunt d’identité, le niveau d’emprunt d’identité demandé (tel que fourni par le paramètre ObjectAttributes ) du nouveau jeton ne doit pas être supérieur au niveau d’emprunt d’identité du jeton existant. Sinon, ZwDuplicateToken retourne STATUS_BAD_IMPERSONATION_LEVEL. |
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 :
| Code de retour | Description |
|---|---|
| STATUS_ACCESS_VIOLATION | Une violation d’accès à la mémoire s’est produite. Par exemple, si le mode précédent était en mode utilisateur et que la mémoire en mode utilisateur non valide a été fournie, ZwDuplicateToken retourne STATUS_ACCESS_VIOLATION. |
| STATUS_INSUFFICIENT_RESOURCES | La mémoire suffisante n’a pas pu être allouée pour dupliquer le nouveau jeton. |
| STATUS_INVALID_PARAMETER | Un paramètre non valide a été détecté. |
| STATUS_BAD_IMPERSONATION_LEVEL | Le niveau d’emprunt d’identité demandé pour le nouveau jeton est supérieur au niveau d’emprunt d’identité du jeton existant. |
| STATUS_ACCESS_DENIED | ZwDuplicateToken retourne STATUS_ACCESS_DENIED s’il n’a pas pu accéder à ExistingTokenHandle. Cela se produit si le jeton existant n’a pas le droit d’accès TOKEN_DUPLICATE. |
| STATUS_INVALID_HANDLE | ZwDuplicateToken retourne STATUS_INVALID_HANDLE si ExistingTokenHandle fait référence à un handle non valide. |
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
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 |
| Plateforme cible | Universal |
| En-tête | ntifs.h (inclure Ntifs.h, FltKernel.h) |
| Bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Règles de conformité DDI | HwStorPortProhibitedDDIs(storport),PowerIrpDDis(wdm) |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour