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 |
|---|---|
|
Il n’a pas été possible d’emprunter l’identité d’un client en raison de restrictions de travail. |
|
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) |