Fonction NtOpenThreadTokenEx (ntifs.h)

Article
02/29/2024

La routine NtOpenThreadTokenEx ouvre le jeton d’accès associé à un thread.

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtOpenThreadTokenEx(
  [in]  HANDLE      ThreadHandle,
  [in]  ACCESS_MASK DesiredAccess,
  [in]  BOOLEAN     OpenAsSelf,
  [in]  ULONG       HandleAttributes,
  [out] PHANDLE     TokenHandle
);

Paramètres

[in] ThreadHandle

Gérez le thread dont le jeton d’accès doit être ouvert. Le handle doit avoir un accès THREAD_QUERY_INFORMATION. Utilisez la macro NtCurrentThread pour spécifier le thread actuel.

[in] DesiredAccess

ACCESS_MASK structure spécifiant les types d’accès demandés au jeton d’accès. Ces types d’accès demandés sont comparés à la liste de contrôle d’accès discrétionnaire (DACL) du jeton pour déterminer quels droits d’accès sont accordés ou refusés.

[in] OpenAsSelf

Valeur booléenne spécifiant si l’accès case activée doit être effectué par rapport au contexte de sécurité du thread appelant NtOpenThreadTokenEx ou par rapport au contexte de sécurité du processus pour le thread appelant.

Si ce paramètre a la valeur FALSE, l’accès case activée est effectué à l’aide du contexte de sécurité du thread appelant. Si le thread emprunte l’identité d’un client, ce contexte de sécurité peut être celui d’un processus client. Si ce paramètre a la valeur TRUE, l’accès case activée est effectué à l’aide du contexte de sécurité du processus pour le thread appelant.

[in] HandleAttributes

Attributs du handle créé. Seul OBJ_KERNEL_HANDLE est actuellement pris en charge. Si l’appelant n’est pas en cours d’exécution dans le contexte de processus système, il doit spécifier OBJ_KERNEL_HANDLE pour ce paramètre.

[out] TokenHandle

Pointeur vers une variable allouée à l’appelant qui reçoit un handle pour le jeton d’accès nouvellement ouvert.

Valeur retournée

NtOpenThreadTokenEx retourne STATUS_SUCCESS ou une status d’erreur appropriée. Les codes status d’erreur possibles sont les suivants :

Code de retour	Description
STATUS_ACCESS_DENIED
ThreadHandle n’avait pas d’accès THREAD_QUERY_INFORMATION.
STATUS_CANT_OPEN_ANONYMOUS	Le client a demandé le niveau d’emprunt d’identité SecurityAnonymous. Toutefois, un jeton anonyme ne peut pas être ouvert. Pour plus d’informations, consultez SECURITY_IMPERSONATION_LEVEL.
STATUS_INVALID_HANDLE	ThreadHandle n’était pas un handle valide.
STATUS_INVALID_PARAMETER	Les HandleAttributes spécifiés n’incluaient pas OBJ_KERNEL_HANDLE.
STATUS_NO_TOKEN	Une tentative a été effectuée pour ouvrir un jeton associé à un thread qui n’emprunte pas actuellement l’identité d’un client.
STATUS_OBJECT_TYPE_MISMATCH	ThreadHandle n’était pas un handle de thread.

Remarques

NtOpenThreadTokenEx ouvre le jeton d’accès associé à un thread et retourne un handle pour ce jeton.

Le paramètre OpenAsSelf permet à un processus serveur d’ouvrir le jeton d’accès d’un processus client lorsque le processus client a spécifié le niveau d’emprunt d’identité SecurityIdentification pour le type énuméré SECURITY_IMPERSONATION_LEVEL . Sans ce paramètre, le processus appelant n’est pas en mesure d’ouvrir le jeton d’accès du client à l’aide du contexte de sécurité du client, car il est impossible d’ouvrir des objets de niveau exécutif à l’aide du niveau d’emprunt d’identité SecurityIdentification.

Tout handle obtenu en appelant NtOpenThreadTokenEx doit finalement être libéré en appelant NtClose.

Les routines de pilote qui s’exécutent dans un contexte de processus autre que celui du processus système doivent définir l’attribut OBJ_KERNEL_HANDLE pour le paramètre HandleAttributes de NtOpenThreadTokenEx. Cela limite l’utilisation du handle retourné par NtOpenThreadTokenEx aux processus en cours d’exécution en mode noyau. Sinon, le handle est accessible par le processus dans le contexte dans lequel le pilote est en cours d’exécution.

Pour plus d’informations sur la sécurité et le contrôle d’accès, consultez Modèle de sécurité Windows pour les développeurs de pilotes et la documentation sur ces rubriques dans le Kit de développement logiciel (SDK) Windows.

Pour les appels provenant 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 Using Nt and Zw Versions of the Native System Services Routines.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP
Plateforme cible	Universal
En-tête	ntifs.h (include Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs, PowerIrpDDis