Fonction NtDuplicateToken (ntifs.h)
La fonction NtDuplicateToken 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
__kernel_entry NTSYSCALLAPI NTSTATUS NtDuplicateToken(
[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 à 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. NtDuplicateToken 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 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 au niveau du bit OU d’une ou plusieurs des valeurs suivantes :
| Valeur | Signification |
|---|---|
| Suppression | Obligatoire pour supprimer l’objet. |
| READ_CONTROL | Obligatoire 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 | Obligatoire pour modifier les informations DACL pour l’objet. |
| WRITE_OWNER | Obligatoire pour modifier les informations de propriété dans le descripteur de sécurité de l’objet (SECURITY_DESCRIPTOR). |
| ACCESS_SYSTEM_SECURITY | Obligatoire pour obtenir ou définir la liste SACL dans la liste de contrôle d’accès 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 comme égal à READ_CONTROL. |
| STANDARD_RIGHTS_WRITE | Actuellement défini comme égal à READ_CONTROL. |
| STANDARD_RIGHTS_EXECUTE | Actuellement défini comme égal à READ_CONTROL. |
| STANDARD_RIGHTS_REQUIRED | Combine l’accès DELETE, READ_CONTROL, WRITE_DAC et 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 à STANDARD_RIGHTS_REQUIRED. |
| TOKEN_ADJUST_DEFAULT | Obligatoire pour modifier le propriétaire par défaut, le groupe principal ou la liste de contrôle d’accès d’un jeton d’accès. |
| TOKEN_ADJUST_GROUPS | Obligatoire pour ajuster les attributs des groupes dans un jeton d’accès. |
| TOKEN_ADJUST_PRIVILEGES | Obligatoire pour activer ou désactiver les privilèges dans un jeton d’accès. |
| TOKEN_ADJUST_SESSIONID | Obligatoire 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 | Obligatoire 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 | Obligatoire pour attacher un jeton d’accès d’emprunt d’identité à un processus. |
| TOKEN_QUERY | Obligatoire pour interroger un jeton d’accès. |
| TOKEN_QUERY_SOURCE | Obligatoire 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. 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 SECURITY_IMPERSONATION_LEVEL niveau d’emprunt d’identité.
[in] EffectiveOnly
Valeur booléenne qui indique si l’intégralité 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 seront 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é (comme fourni par le paramètre ObjectAttributes ) de SecurityImpersonation ou SecurityDelegation. Sinon, NtDuplicateToken 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, NtDuplicateToken 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
NtDuplicateToken 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 le mode utilisateur et que la mémoire en mode utilisateur non valide a été fournie, NtDuplicateToken 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 | NtDuplicateToken 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 | 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 NtDuplicateToken, consultez DuplicateTokenEx dans la documentation SDK Windows.
Une fois que vous avez terminé d’utiliser le nouveau jeton, appelez la fonction NtClose pour fermer le handle de jeton.
Si l’appel à la fonction NtDuplicateToken se produit en mode utilisateur, vous devez utiliser le nom « NtDuplicateToken » au lieu de « NtDuplicateToken ».
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, PowerIrpDDis |