WSASetSocketPeerTargetName, fonction (ws2tcpip.h)

Article
08/28/2023

La fonction WSASetSocketPeerTargetName est utilisée pour spécifier le nom de cible d’homologue (SPN) qui correspond à une adresse IP d’homologue. Ce nom cible est destiné à être spécifié par les applications clientes pour identifier en toute sécurité l’homologue qui doit être authentifié.

Syntaxe

INT WSAAPI WSASetSocketPeerTargetName(
  [in]           SOCKET                             Socket,
  [in]           const SOCKET_PEER_TARGET_NAME      *PeerTargetName,
  [in]           ULONG                              PeerTargetNameLen,
  [in, optional] LPWSAOVERLAPPED                    Overlapped,
  [in, optional] LPWSAOVERLAPPED_COMPLETION_ROUTINE CompletionRoutine
);

Paramètres

[in] Socket

Descripteur identifiant un socket sur lequel le nom de cible homologue est attribué.

[in] PeerTargetName

Pointeur vers une structure SOCKET_PEER_TARGET_NAME qui définit le nom de la cible homologue.

[in] PeerTargetNameLen

Taille, en octets, du paramètre PeerTargetName .

[in, optional] Overlapped

Pointeur vers une structure WSAOVERLAPPED . Ce paramètre est ignoré pour les sockets qui ne se chevauchent pas.

[in, optional] CompletionRoutine

Pointeur vers la routine d’achèvement appelée une fois l’opération terminée. Ce paramètre est ignoré pour les sockets qui ne se chevauchent pas.

Valeur retournée

Si la fonction aboutit, la valeur de retour est égale à zéro. 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
WSAEAFNOSUPPORT	La famille d’adresses spécifiée n’est pas prise en charge.
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 PeerTargetName était un pointeur NULL .
WSAEINVAL	Un paramètre non valide a été passé. Cette erreur est retournée si le socket passé dans le paramètre Socket n’a pas été créé avec une famille d’adresses du AF_INET ou AF_INET6 et un type de socket de SOCK_DGRAM ou de SOCK_STREAM. Cette erreur est également retournée pour un socket sans connexion si l’adresse IP et le port sont zéro dans le membre PeerAddress de la structure SOCKET_PEER_TARGET_NAME pointée par le paramètre PeerTargetName .
WSAEISCONN	Le socket est connecté. Cette fonction n’est pas autorisée avec un socket connecté, que le socket soit orienté connexion ou sans connexion.
WSAEMSGSIZE	Une mémoire tampon passée était trop petite.
WSAENOTSOCK	Le descripteur passé dans le paramètre Socket n’est pas un socket valide.

Remarques

La fonction WSASetSocketPeerTargetName fournit une méthode pour spécifier le nom cible qui correspond à un principal de sécurité homologue. Cette fonction est destinée à être utilisée par une application cliente pour identifier l’homologue qui doit être authentifié. Une application cliente doit spécifier le nom de la cible d’homologue afin d’empêcher les attaques de l’intercepteur approuvé. Pour les sockets sans connexion, une application peut appeler la fonction WSASetSocketPeerTargetName plusieurs fois pour spécifier différents noms de cibles pour différentes adresses IP homologues.

Cette fonction simplifie l’appel de la fonction WSAIoctl avec un paramètre dwIoControlCode défini sur SIO_SET_PEER_TARGET_NAME.

Pour les sockets orientés connexion, la fonction WSASetSocketPeerTargetName doit être appelée avant WSAConnect. Pour les sockets sans connexion, cette fonction doit être appelée avant WSAConnect ou avant le premier appel WSASendTo dirigé vers l’adresse de l’homologue.

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.

Spécifications


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