Partager via


Fonction PsImpersonateClient (ntifs.h)

La routine PsImpersonateClient oblige un thread de serveur à emprunter l’identité d’un client.

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 doit 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 sur NULL pour mettre fin à l’emprunt d’identité.

[in] CopyOnOpen

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

[in] EffectiveOnly

Définissez sur FALSE pour permettre au serveur d’activer les groupes et les privilèges actuellement désactivés dans le contexte de sécurité du 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 retournée

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

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

Remarques

PsImpersonateClient oblige le thread de serveur spécifié à emprunter l’identité du client spécifié.

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

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

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

La routine PsImpersonateClient peut échouer à renvoyer le thread serveur à l’emprunt d’identité précédente si le thread emprunte déjà l’identité ou s’il existe des restrictions de travail.

La routine vérifie si l’emprunt d’identité du client peut effectivement se produire en vérifiant diverses 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é (SID) égaux.
  • Aucun des jetons n’est restreint

Si aucune des conditions n’est remplie, la routine effectue une copie du jeton existant passé à l’appel et affecte le jeton nouvellement copié en tant que jeton d’emprunt d’identité avec un niveau d’emprunt d’identité de sécurité limité ; autrement dit, le thread de serveur peut uniquement obtenir 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 des privilèges d’un thread utilisateur non approuvé (prendre le thread d’un utilisateur et emprunter l’identité de LocalSystem, par exemple). Si un thread d’utilisateur non approuvé a son privilège déclenché, l’utilisateur peut récupérer le jeton de thread une fois qu’il a été élevé et compromettre 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 amener un thread à emprunter l’identité d’un utilisateur.

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.

Configuration requise

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

Voir aussi

PsGetCurrentThread

PsReferenceImpersonationToken

PsRevertToSelf

SECURITY_IMPERSONATION_LEVEL

SeImpersonateClientEx