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 à attribuer comme jeton d’emprunt d’identité. Ce jeton peut être un jeton principal ou un jeton d’emprunt d’identité. Défini sur NULL pour mettre fin à l’emprunt d’identité.
[in] CopyOnOpen
Spécifie si le jeton peut être ouvert directement. Défini 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 la valeur FALSE pour permettre 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é 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 de retour
PsImpersonateClient retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple :
| Retourner le code | Description |
|---|---|
|
Il n’était pas possible d’emprunter l’identité d’un client en raison de restrictions de travail. |
|
Il n’y avait pas de mémoire suffisante pour terminer l’opération. |
Remarques
PsImpersonateClient entraîne l’emprunt d’identité du client 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 d’enregistrer le pointeur retourné par PsReferenceImpersonationToken.
Pour mettre fin à la nouvelle emprunt d’identité et renvoyer le thread de serveur à l’emprunt d’identité précédent, appelez PsImpersonateClient à nouveau, 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 de serveur à son contexte de sécurité d’origine (c’est-à-dire celui représenté par son jeton principal), appelez PsImpersonateClient à nouveau, en passant un pointeur NULL pour le paramètre Token.
La routine PsImpersonateClient peut échouer à renvoyer le thread de serveur à l’emprunt d’identité précédent si le thread est déjà emprunt d’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 passé 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é comme jeton d’emprunt d’identité, bien qu’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é a eu 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 plus élevé 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 par un thread.
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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP |
| plateforme cible | Universel |
| d’en-tête | ntifs.h (include Ntifs.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| règles de conformité DDI | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |