WSAQuerySocketSecurity, fonction (ws2tcpip.h)

Article
03/04/2024

La fonction WSAQuerySocketSecurity interroge des informations sur la sécurité appliquée à une connexion sur un socket.

Syntaxe

INT WSAAPI WSAQuerySocketSecurity(
  [in]            SOCKET                               Socket,
  [in, optional]  const SOCKET_SECURITY_QUERY_TEMPLATE *SecurityQueryTemplate,
  [in]            ULONG                                SecurityQueryTemplateLen,
  [out, optional] SOCKET_SECURITY_QUERY_INFO           *SecurityQueryInfo,
  [in, out]       ULONG                                *SecurityQueryInfoLen,
  [in, optional]  LPWSAOVERLAPPED                      Overlapped,
  [in, optional]  LPWSAOVERLAPPED_COMPLETION_ROUTINE   CompletionRoutine
);

Paramètres

[in] Socket

Descripteur identifiant un socket pour lequel les informations de sécurité sont interrogées.

[in, optional] SecurityQueryTemplate

Pointeur vers une structure SOCKET_SECURITY_QUERY_TEMPLATE qui spécifie le type d’informations de requête à retourner.

Une structure SOCKET_SECURITY_QUERY_TEMPLATE pointée par ce paramètre peut contenir des zéros pour que tous les membres demandent des informations de sécurité par défaut. En cas de retour réussi, seul le membre Flags du SOCKET_SECURITY_QUERY_INFO sera défini dans le paramètre SecurityQueryInfo retourné.

Ce paramètre peut être un pointeur NULL si le paramètre Socket a été créé avec un protocole de IPPROTO_TCP. Dans ce cas, les informations retournées sont identiques à celles d’une structure SOCKET_SECURITY_QUERY_TEMPLATE avec toutes les valeurs définies sur zéro. Ce paramètre doit être spécifié pour un socket avec le protocole de IPPROTO_TCP si plus d’informations de sécurité par défaut sont requises.

Si la structure SOCKET_SECURITY_QUERY_TEMPLATE est spécifiée avec le membre PeerTokenAccessMask non spécifié (défini sur zéro), la fonction WSAQuerySocketSecurity ne retourne pas les membres PeerApplicationAccessTokenHandle et PeerMachineAccessTokenHandle dans la structure SOCKET_SECURITY_QUERY_INFO .

Si un paramètre Socket a été créé avec un protocole non égal à IPPROTO_TCP, le paramètre SecurityQueryTemplate doit être spécifié. Dans ce cas, le membre PeerAddress de la structure SOCKET_SECURITY_QUERY_TEMPLATE doit spécifier une famille d’adresses de AF_INET ou de AF_INET6, ainsi que l’adresse IP et le numéro de port de l’homologue.

[in] SecurityQueryTemplateLen

Taille, en octets, du paramètre SecurityQueryTemplate .

Ce paramètre peut être égal à zéro si le paramètre Socket a été créé avec un protocole de IPPROTO_TCP. Sinon, ce paramètre doit correspondre à la taille d’une structure SOCKET_SECURITY_QUERY_TEMPLATE .

[out, optional] SecurityQueryInfo

Pointeur vers une mémoire tampon qui recevra une structure SOCKET_SECURITY_QUERY_INFO contenant les informations interrogées. Cette valeur peut être définie sur NULL pour interroger la taille de la mémoire tampon de sortie.

[in, out] SecurityQueryInfoLen

En entrée, pointeur vers la taille, en octets, du paramètre SecurityQueryInfo . Si la mémoire tampon est trop petite pour recevoir les informations interrogées, l’appel retourne SOCKET_ERROR et le nombre d’octets nécessaires pour retourner les informations interrogées est défini dans la valeur indiquée par ce paramètre. Lors d’un appel réussi, le nombre d’octets copiés est retourné.

[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.
WSAECONNRESET	Pour un socket de flux, le circuit virtuel a été réinitialisé par le côté distant. L’application doit fermer le socket, car il n’est plus utilisable. Pour un socket de datagramme UDP, cette erreur indique qu’une opération d’envoi précédente a entraîné un message ICMP « Port inaccessible ».
WSAEFAULT	Le système a détecté une adresse de pointeur non valide lors de la tentative d’utilisation d’un paramètre. Cette erreur est retournée si le paramètre SecurityQueryInfoLen était un pointeur NULL .
WSAEINVAL	Un paramètre non valide a été passé. Cette erreur est retournée si le socket transmis 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 SOCK_STREAM.
WSAEMSGSIZE	Une mémoire tampon passée était trop petite. Cette erreur est retournée pour un paramètre Socket lorsque le protocole n’a pas été IPPROTO_TCP si le paramètre SecurityQueryInfo est un pointeur NULL ou si le paramètre SecurityQueryTemplateLen est inférieur à la taille d’une structure de SOCKET_SECURITY_QUERY_TEMPLATE .
WSAENOTSOCK	Le descripteur transmis dans le paramètre Socket n’est pas un socket valide.

Remarques

La fonction WSAQuerySocketSecurity fournit une méthode pour interroger les paramètres de sécurité actuels sur un socket. Une fois la connexion établie, la fonction WSAQuerySocketSecurity permet à une application d’interroger les propriétés de sécurité de la connexion, ce qui peut inclure des informations sur les jetons d’accès d’homologue.

Pour les sockets orientés connexion, il est préférable d’appeler la fonction WSAQuerySocketSecurity immédiatement après l’établissement d’une connexion. Pour les sockets sans connexion, il est préférable d’appeler la fonction WSAQuerySocketSecurity immédiatement après que les données ont été envoyées à une nouvelle adresse d’homologue ou reçues d’une nouvelle adresse d’homologue. La fonction WSAQuerySocketSecurity peut être appelée plusieurs fois sur un seul socket.

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

La fonction WSAQuerySocketSecurity peut être appelée sur un paramètre Socket créé avec une famille d’adresses de AF_INET ou de AF_INET6.

Si le paramètre Socket a été créé avec un protocole de IPPROTO_TCP, le paramètre SecurityQueryTemplate peut être NULL et le paramètre SecurityQueryTemplateLen peut être égal à zéro. Sinon, le paramètre SecurityQueryTemplate doit pointer vers une structure SOCKET_SECURITY_QUERY_TEMPLATE .

Pour une application cliente utilisant des sockets orientés connexion (socket créé avec un protocole de IPPROTO_TCP), la fonction WSAQuerySocketSecurity doit être appelée après le retour de la fonction connect, ConnectEx ou WSAConnect . Pour une application serveur utilisant des sockets orientés connexion (protocole de IPPROTO_TCP), la fonction WSAQuerySocketSecurity doit être appelée après les retours de la fonction accept, AcceptEx ou WSAAccept .

Pour les sockets sans connexion (socket créé avec un protocole de IPPROTO_UDP), l’application doit appeler la fonction WSAQuerySocketSecurity immédiatement après les retours d’appel WSASendTo ou WSARecvFrom pour une nouvelle adresse d’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.

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