PsImpersonateClient, fonction (ntifs.h)

La routine PsImpersonateClient entraîne l’emprunt d’identité d’un client par un thread de serveur.

Syntaxe

NTSTATUS PsImpersonateClient(
  [in, out] PETHREAD                     Thread,
  [in]      PACCESS_TOKEN                Token,
  [in]      BOOLEAN                      CopyOnOpen,
  [in]      BOOLEAN                      EffectiveOnly,
  [in]      SECURITY_IMPERSONATION_LEVEL ImpersonationLevel
);

Paramètres

[in, out] Thread

Pointeur vers le thread de serveur qui consiste à emprunter l’identité du client.

[in] Token

Pointeur vers le jeton à affecter en tant que jeton d’emprunt d’identité. Ce jeton peut être un jeton principal ou un jeton d’emprunt d’identité. Définissez la valeur NULL pour mettre fin à l’emprunt d’identité.

[in] CopyOnOpen

Spécifie si le jeton peut être ouvert directement. Définissez la valeur TRUE pour spécifier que le jeton ne peut pas être ouvert directement. Dans ce cas, le jeton doit être dupliqué et le jeton en double utilisé à la place. Définissez la valeur FALSE pour autoriser l’ouverture directe du jeton.

[in] EffectiveOnly

Définissez la valeur FALSE pour permettre au serveur d’activer des groupes et des privilèges actuellement désactivés dans le contexte de sécurité client, TRUE sinon.

[in] ImpersonationLevel

Valeur SECURITY_IMPERSONATION_LEVEL qui spécifie le niveau d’emprunt d’identité auquel le serveur doit accéder au jeton.

Valeur de retour

PsImpersonateClient retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple :

Code de retour Description
STATUS_ACCESS_DENIED
Il n’était pas possible d’emprunter l’identité d’un client en raison de restrictions de travail.
STATUS_NO_MEMORY
Il n’y avait pas de mémoire suffisante pour terminer l’opération.

Remarques

PsImpersonateClient provoque l’emprunt d’identité du thread de serveur spécifié.

Le thread de serveur peut déjà emprunter l’identité d’un client lorsque PsImpersonateClient est appelé. Si c’est le cas, le nombre de références sur le jeton représentant ce client est décrémenté. Pour conserver ce jeton pour une utilisation ultérieure, les pilotes doivent appeler PsReferenceImpersonationToken avant d’appeler PsImpersonateClient et enregistrer le pointeur retourné par PsReferenceImpersonationToken.

Pour terminer la nouvelle emprunt d’identité et renvoyer le thread de serveur à l’emprunt d’identité précédent, appelez à nouveau PsImpersonateClient , en passant le pointeur enregistré pour le paramètre Token . Pour terminer toutes les emprunts d’identité, appelez la routine PsRevertToSelf .

Sinon, pour mettre fin à l’emprunt d’identité et renvoyer le thread de serveur à son contexte de sécurité d’origine (autrement dit, celui représenté par son jeton principal), appelez à nouveau PsImpersonateClient , en passant un pointeur NULL pour le paramètre Token .

La routine PsImpersonateClient ne peut pas retourner correctement le thread de serveur à l’emprunt d’identité précédent si le thread emprunte déjà l’identité ou qu’il existe des restrictions de travail.

La routine garantit si l’emprunt d’identité du client peut réellement se produire en vérifiant différentes conditions, notamment les suivantes :

  • Le jeton transmis par l’appelant n’a pas d’ID d’authentification anonyme
  • Le jeton du processus référencé à partir du thread de serveur et le jeton donné ont des identificateurs de sécurité égaux (SID)
  • Aucun des jetons n’est limité

Si aucune des conditions n’est remplie, la routine effectue une copie du jeton existant passé à l’appel et affecte le jeton nouvellement copié comme jeton d’emprunt d’identité, mais avec un niveau d’emprunt d’identité de sécurité limité; autrement dit, le thread de serveur ne peut obtenir que des informations sur le client. Si la copie de jeton n’est pas possible, la routine échoue avec un code NTSTATUS.

Il est extrêmement dangereux de déclencher l’état de privilège d’un thread utilisateur non approuvé (prenez le thread d’un utilisateur et empruntez l’identité de LocalSystem, par exemple). Si un thread d’utilisateur non approuvé avait son privilège déclenché, l’utilisateur peut récupérer le jeton de thread une fois qu’il a été élevé et subvertir la sécurité de l’ensemble du système.

Dans les cas où un état de privilège supérieur est requis, la tâche doit être distribuée dans une file d’attente de travail où la tâche peut être gérée en toute sécurité par le thread de travail système. De cette façon, aucune emprunt d’identité n’est nécessaire.

La routine SeImpersonateClientEx peut être utilisée pour provoquer l’emprunt d’identité d’un utilisateur.

Pour plus d’informations sur le contrôle d’accès et de sécurité, consultez la documentation sur ces rubriques dans le Microsoft Windows SDK.

Configuration requise

   
Client minimal pris en charge Disponible dans Windows XP et versions ultérieures des systèmes d’exploitation Windows.
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 HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

Voir aussi

PsGetCurrentThread

PsReferenceImpersonationToken

PsRevertToSelf

SECURITY_IMPERSONATION_LEVEL

SeImpersonateClientEx