WSASetSocketSecurity, fonction (ws2tcpip.h)

Article
12/22/2023

La fonction WSASetSocketSecurity active et applique la sécurité pour un socket.

Syntaxe

INT WSAAPI WSASetSocketSecurity(
  [in]           SOCKET                             Socket,
  [in, optional] const SOCKET_SECURITY_SETTINGS     *SecuritySettings,
  [in]           ULONG                              SecuritySettingsLen,
  [in, optional] LPWSAOVERLAPPED                    Overlapped,
  [in, optional] LPWSAOVERLAPPED_COMPLETION_ROUTINE CompletionRoutine
);

Paramètres

[in] Socket

Descripteur qui identifie un socket sur lequel les paramètres de sécurité sont appliqués.

[in, optional] SecuritySettings

Pointeur vers une structure de SOCKET_SECURITY_SETTINGS qui spécifie les paramètres de sécurité à appliquer au trafic du socket. Si ce paramètre a la valeur NULL, les paramètres par défaut sont appliqués au socket.

[in] SecuritySettingsLen

Taille, en octets, du paramètre SecuritySettings .

[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.
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. Cette erreur est également retournée si la structure SOCKET_SECURITY_SETTINGS pointée par le paramètre SecuritySettings a une valeur incorrecte.
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 transmis dans le paramètre Socket n’est pas un socket valide.

Remarques

L’objectif principal de la fonction WSASetSocketSecurity est d’activer la sécurité d’un socket s’il n’est pas déjà activé par la stratégie administrative. Pour IPsec, cela signifie que les filtres et stratégies IPsec appropriés seront instanciés, qui seront utilisés pour sécuriser ce socket. La fonction WSASetSocketSecurity peut également être utilisée pour définir des exigences de sécurité spécifiques pour le socket.

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

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

Pour une application cliente utilisant des sockets orientés connexion (protocole de IPPROTO_TCP), la fonction WSASetSocketSecurity doit être appelée avant l’appel de la fonction connect, ConnectEx ou WSAConnect . Si la fonction WSASetSocketSecurity est appelée après la fonction connect, ConnectEx ou WSAConnect , WSASetSocketSecurity doit échouer.

Pour une application serveur utilisant des sockets orientés connexion (protocole de IPPROTO_TCP), la fonction WSASetSocketSecurity doit être appelée avant l’appel de la fonction bind . Si la fonction WSASetSocketSecurity est appelée après la fonction bind , WSASetSocketSecurity doit échouer.

Pour les sockets sans connexion (protocole de IPPROTO_UDP), l’application doit appeler la fonction WSASetSocketSecurity immédiatement après le retour du socket ou de l’appel WSASocket .

Les applications serveur doivent appeler la fonction setsockopt pour obtenir un accès exclusif au port utilisé par le socket. Cela empêche d’autres applications d’utiliser le même port. La fonction setsockopt est appelée avec le paramètre de niveau défini sur SOL_SOCKET, le paramètre optname défini sur SO_EXCLUSIVEADDRUSE et le paramètre valeur défini sur zéro. La fonction WSASetSocketSecurity appelle en interne le setockopt avec SO_EXCLUSIVEADDRUSE pour obtenir un accès exclusif au port. Cela permet de s’assurer que le socket n’est pas vulnérable aux attaques d’autres applications s’exécutant sur l’ordinateur local.

Les paramètres de sécurité non définis à l’aide de WSASetSocketSecurity sont dérivés de la stratégie par défaut système ou de la stratégie configurée administrativement. Il est recommandé que la plupart des applications spécifient une valeur de SOCKET_SECURITY_PROTOCOL_DEFAULT pour l’énumération SOCKET_SECURITY_PROTOCOL dans le membre SecurityProtocol du SOCKET_SECURITY_PROTOCOL pointé vers le paramètre SecuritySettings . Cela rend l’application neutre pour les protocoles de sécurité et facilite les déploiements entre différents systèmes.

Lorsque le paramètre SecuritySettings pointe vers une structure SOCKET_SECURITY_SETTINGS_IPSEC , le membre SecurityProtocol de la structure doit être défini sur SOCKET_SECURITY_PROTOCOL_IPSEC, et non sur SOCKET_SECURITY_PROTOCOL_DEFAULT.

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.
L’application doit définir ses paramètres de sécurité avant d’appeler les fonctions bind, connect, ConnectEx ou WSAConnect .
La fonction WSASetSocketSecurity ne peut être appelée qu’une seule fois par socket.

Stratégie IPsec de socket sécurisé par défaut

Si le paramètre SecuritySettings a la valeur NULL et qu’il n’existe aucune autre stratégie IPsec spécifiée administrativement sur l’ordinateur, une stratégie de sécurité par défaut basée sur IPsec sera utilisée pour sécuriser le trafic de l’application. Certains types d’informations d’identification d’authentification (un certificat utilisateur ou une appartenance à un domaine, par exemple) doivent être présents pour qu’IPsec réussisse avec une stratégie par défaut.

La stratégie IPsec par défaut a été conçue pour que la sécurité IPsec puisse être négociée dans autant de scénarios que possible.

Authip MM policy = 
{
 Auth methods = {IKE_ANONYMOUS}
 No impersonation
 Proposals = 
 {
   {
     Crypto algos = 
     IKE_CIPHER_AES_128,
     IKE_INTEGRITY_SHA1, 
     IKE_DH_ECP_256
     MM lifetime = 2 hrs
     QM = 0 (infinite)
   }
   {
     Crypto algos = 
     IKE_CIPHER_3DES, 
     IKE_INTEGRITY_SHA1, 
     IKE_DH_GROUP_2
     MM lifetime = 2 hrs
     QM = 0 (infinite)
   }
 }
}

Authip QM policy =
{
 QM proposals = 
 {
   QM lifetime = 1 hr, 55GB,
   Crypto algos = 
   IPSEC_TRANSFORM_ESP_AUTH, 
   IPSEC_AUTH_TRANSFORM_ID_HMAC_SHA_1_96
   No PFS
 }
 {
   QM lifetime = 1 hr, 55GB,
   Crypto algos = 
   IPSEC_TRANSFORM_ESP_AUTH_AND_CIPHER,
   IPSEC_AUTH_TRANSFORM_ID_HMAC_SHA_1_96,
   IPSEC_CIPHER_TRANSFORM_ID_AES_128
   No PFS
 }
 {
   QM lifetime = 1 hr, 55GB,
   Crypto algos = 
   IPSEC_TRANSFORM_ESP_AUTH_AND_CIPHER,
   IPSEC_AUTH_TRANSFORM_ID_HMAC_SHA_1_96,
   IPSEC_CIPHER_TRANSFORM_ID_CBC_3DES
   No PFS
 }
 {
   QM lifetime = 1 hr, 55GB,
   Crypto algos = 
   IPSEC_TRANSFORM_AH,
   IPSEC_AUTH_TRANSFORM_ID_HMAC_SHA_1_96
   No PFS
 }
 IPSEC_POLICY_FLAG_ND_BOUNDARY
 ndAllowClearTimeoutSeconds = 10
 saIdleTimeout = {5mins, 1min}
 UM policy = 
 {
   {IKE_SSL, Null-Root-Config}
   {IKE_KERBEROS}
   {IKE_SSL, Null-Root-Config}
   No impersonation
 } 
}

Configuration requise


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