Fonction WSAImpersonateSocketPeer (ws2tcpip.h)

Article
03/13/2024

La fonction WSAImpersonateSocketPeer est utilisée pour emprunter l’identité du principal de sécurité correspondant à un homologue de socket afin d’effectuer une autorisation au niveau de l’application.

Syntaxe

INT WSAAPI WSAImpersonateSocketPeer(
  [in]           SOCKET         Socket,
  [in, optional] const sockaddr *PeerAddr,
  [in]           ULONG          PeerAddrLen
);

Paramètres

[in] Socket

Identifie le socket d’application.

[in, optional] PeerAddr

Adresse IP de l’homologue à emprunter l’identité. Pour les sockets orientés connexion, le socket connecté identifie un homologue de manière unique. Dans ce cas, ce paramètre est ignoré.

[in] PeerAddrLen

Taille, en octets, du paramètre PeerAddress .

Valeur retournée

Si la fonction réussit, la valeur de retour est 0. Sinon, une valeur de SOCKET_ERROR est retournée et un code d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Certains codes d’erreur possibles sont répertoriés ci-dessous.

Code d'erreur	Signification
WSAEFAULT	Le système a détecté un pointeur d’adresse non valide lors de la tentative d’utilisation d’un argument pointeur d’un appel. Cette erreur est retournée si le paramètre PeerAddr était un pointeur NULL .
WSAEAFNOSUPPORT	La famille d’adresses spécifiée n’est pas prise en charge.
WSAEMSGSIZE	Une mémoire tampon passée était trop petite.
WSAENOTSOCK	Le descripteur transmis dans le paramètre Socket n’est pas un socket valide.

Remarques

La fonction WSAImpersonateSocketPeer permet à une application d’emprunter l’identité du principal de sécurité correspondant à un homologue de socket afin d’effectuer une autorisation au niveau de l’application. Si le jeton d’utilisateur homologue (emprunt d’identité) est disponible, il sera utilisé pour l’emprunt d’identité, sinon, le jeton d’ordinateur homologue sera utilisé. La fonction WSAImpersonateSocketPeer peut être appelée uniquement pour les sockets bloquants et non superposés. Après avoir effectué des vérifications d’autorisation, une application doit appeler la fonction WSARevertImpersonation pour mettre fin à l’emprunt d’identité.

Pour les sockets orientés connexion, la fonction WSAImpersonateSocketPeer doit être appelée après l’établissement d’une connexion. Pour une application serveur utilisant des sockets orientés connexion, le WSAImpersonateSocketPeer doit être appelé après la fonction accept, AcceptEx ou WSAAccept retournée.

Pour les sockets sans connexion, l’application doit appeler la fonction WSAImpersonateSocketPeer immédiatement après les retours de la fonction recv, recvfrom, WSARecvEx, WSARecvEx, WSARecvFrom ou LPFN_WSARECVMSG (WSARecvMsg) pour une nouvelle adresse d’homologue.

La fonction WSAImpersonateSocketPeer peut être appelée plusieurs fois pour un seul socket.

Une erreur est retournée si les conditions suivantes ne sont pas remplies.

La famille d’adresses du paramètre Socket doit être AF_INET ou AF_INET6.
Le type de socket doit être SOCK_STREAM ou SOCK_DGRAM.

La fonction WSARevertImpersonation doit être appelée pour mettre fin à l’emprunt d’identité.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	ws2tcpip.h
Bibliothèque	Fwpuclnt.lib
DLL	Fwpuclnt.dll