WSASetSocketSecurity 函数 (ws2tcpip.h)

项目
12/22/2023

WSASetSocketSecurity 函数为套接字启用并应用安全性。

语法

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
);

参数

[in] Socket

一个描述符，用于标识应用安全设置的套接字。

[in, optional] SecuritySettings

指向 SOCKET_SECURITY_SETTINGS 结构的指针，该结构指定要应用于套接字流量的安全设置。如果此参数为 NULL，则默认设置将应用于套接字。

[in] SecuritySettingsLen

SecuritySettings 参数的大小（以字节为单位）。

[in, optional] Overlapped

指向 WSAOVERLAPPED 结构的指针。对于非重叠套接字，将忽略此参数。

[in, optional] CompletionRoutine

指向完成操作时调用的完成例程的指针。对于非重叠套接字，将忽略此参数。

返回值

如果函数成功，则返回值为 0。否则，将返回 值 SOCKET_ERROR ，并且可以通过调用 WSAGetLastError 来检索特定的错误代码。

下面列出了一些可能的错误代码。

错误代码	含义
WSAEAFNOSUPPORT	：不支持指定的地址系列。
WSAEINVAL	传递的参数无效。如果在 Socket 参数中传递的套接字不是使用AF_INET或AF_INET6的地址系列以及SOCK_DGRAM或SOCK_STREAM的套接字类型创建的，则返回此错误。如果 SecuritySettings 参数指向的 SOCKET_SECURITY_SETTINGS 结构的值不正确，也会返回此错误。
WSAEISCONN	套接字已连接。无论连接套接字是面向连接的还是无连接的套接字，都不允许使用此函数。
WSAEMSGSIZE	传递的缓冲区太小。
WSAENOTSOCK	在 Socket 参数中传递的描述符不是有效的套接字。

注解

WSASetSocketSecurity 函数的主要用途是启用套接字的安全性（如果管理策略尚未启用）。对于 IPsec，这意味着将实例化用于保护此套接字的相应 IPsec 筛选器和策略。 WSASetSocketSecurity 函数还可用于设置套接字的特定安全要求。

此函数简化了调用 WSAIoctl 函数（将 dwIoControlCode 参数设置为 SIO_SET_SECURITY）。

可以在使用 AF_INET 或 AF_INET6 的地址系列创建的 Socket 参数上调用 WSASetSocketSecurity 函数。

对于使用面向连接的套接字 (IPPROTO_TCP) 协议的客户端应用程序，应在调用 connect、ConnectEx 或 WSAConnect 函数之前调用 WSASetSocketSecurity 函数。如果在 connect、ConnectEx 或 WSAConnect 函数之后调用 WSASetSocketSecurity 函数，则 WSASetSocketSecurity 应会失败。

对于使用面向连接的套接字 (IPPROTO_TCP) 协议的服务器应用程序，应在调用绑定函数之前调用 WSASetSocketSecurity 函数。如果在绑定函数之后调用 WSASetSocketSecurity 函数，则 WSASetSocketSecurity 应会失败。

对于无连接套接字 (IPPROTO_UDP) 协议，应用程序应在套接字或 WSASocket 调用返回后立即调用 WSASetSocketSecurity 函数。

服务器应用程序应调用 setsockopt 函数来获取对套接字使用的端口的独占访问权限。这会阻止其他应用程序使用相同的端口。将调用 setsockopt 函数，级别参数设置为 SOL_SOCKET，optname 参数设置为 SO_EXCLUSIVEADDRUSE，值参数设置为非零。 WSASetSocketSecurity 函数在内部调用具有SO_EXCLUSIVEADDRUSE的 setsockopt，以获取对端口的独占访问权限。这是为了确保套接字不会受到本地计算机上运行的其他应用程序的攻击。

未使用 WSASetSocketSecurity 设置的安全设置派生自系统默认策略或管理配置的策略。建议大多数应用程序在SecuritySettings 参数指向的 SOCKET_SECURITY_PROTOCOL的 SecurityProtocol 成员中为 SOCKET_SECURITY_PROTOCOL 枚举指定值SOCKET_SECURITY_PROTOCOL_DEFAULT。这使得应用程序与安全协议无关，并允许在不同系统之间更轻松地部署。

当 SecuritySettings 参数指向 SOCKET_SECURITY_SETTINGS_IPSEC 结构时，结构的 SecurityProtocol 成员必须设置为 SOCKET_SECURITY_PROTOCOL_IPSEC，而不是 SOCKET_SECURITY_PROTOCOL_DEFAULT。

如果不满足以下条件，将返回错误。

Socket 参数的地址系列必须是AF_INET或AF_INET6。
套接字类型必须是SOCK_STREAM或SOCK_DGRAM。
应用程序必须在调用 bind、 connect、 ConnectEx 或 WSAConnect 函数之前设置其安全设置。
每个套接字只能调用 WSASetSocketSecurity 函数一次。

默认安全套接字 IPsec 策略

如果 SecuritySettings 参数设置为 NULL，并且计算机上没有其他管理指定的 IPsec 策略，则将使用基于 IPsec 的默认安全策略来保护应用程序的流量。某些类型的身份验证凭据 (用户证书或域成员身份，例如，必须存在) 才能使 IPsec 使用默认策略成功。

已设计默认 IPsec 策略，以便在尽可能多的方案中协商 IPsec 安全性。

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
 } 
}

要求


最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	ws2tcpip.h
Library	Fwpuclnt.lib
DLL	Fwpuclnt.dll