Функция 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

Указатель на подпрограмму завершения, вызываемую при завершении операции. Этот параметр игнорируется для неперекрывающихся сокетов.

Возвращаемое значение

Если вызов функции заканчивается удачно, возвращается нулевое значение. В противном случае возвращается значение SOCKET_ERROR , а определенный код ошибки можно получить, вызвав WSAGetLastError.

Ниже перечислены некоторые возможные коды ошибок.

Код ошибки	Значение
WSAEAFNOSUPPORT	Указанное семейство адресов не поддерживается.
WSAEINVAL	Передан недопустимый параметр. Эта ошибка возвращается, если сокет, переданный в параметре Socket , не был создан с семейством адресов AF_INET или AF_INET6 и типом сокета SOCK_DGRAM или SOCK_STREAM. Эта ошибка также возвращается, если структура SOCKET_SECURITY_SETTINGS , на которую указывает параметр SecuritySettings , имеет неверное значение.
WSAEISCONN	Сокет подключен. Эта функция не разрешена с подключенным сокетом, независимо от того, является ли сокет ориентированным на подключение или без подключения.
WSAEMSGSIZE	Переданный буфер был слишком мал.
WSAENOTSOCK	Дескриптор, передаваемый в параметре Socket , не является допустимым сокетом.

Основная цель функции WSASetSocketSecurity — включить безопасность для сокета, если она еще не включена политикой администрирования. Для IPsec это означает, что будут создаваться соответствующие фильтры и политики IPsec, которые будут использоваться для защиты этого сокета. Функцию WSASetSocketSecurity также можно использовать для установки определенных требований к безопасности для сокета.

Эта функция упрощает вызов функции WSAIoctl с параметром dwIoControlCode, для SIO_SET_SECURITY.

Функция WSASetSocketSecurity может вызываться в параметре Socket , созданном с семейством адресов AF_INET или AF_INET6.

Для клиентского приложения, использующее сокеты, ориентированные на подключение (протокол IPPROTO_TCP), необходимо вызвать функцию WSASetSocketSecurity перед вызовом функции connect, ConnectEx или WSAConnect . Если функция WSASetSocketSecurity вызывается после функции connect, ConnectEx или WSAConnect , WSASetSocketSecurity должна завершиться ошибкой.

Для серверного приложения, использующее сокеты, ориентированные на подключение (протокол IPPROTO_TCP), необходимо вызвать функцию WSASetSocketSecurity перед вызовом функции bind . Если функция WSASetSocketSecurity вызывается после функции bind , WSASetSocketSecurity должен завершиться ошибкой.

Для сокетов без подключения (протокол IPPROTO_UDP) приложение должно вызывать функцию WSASetSocketSecurity сразу после возврата сокета или вызова WSASocket .

Серверные приложения должны вызывать функцию setsockopt , чтобы получить монопольный доступ к порту, используемому сокетом. Это не позволит другим приложениям использовать тот же порт. Функция setsockopt будет вызываться с параметром уровня , равным SOL_SOCKET, параметру optname — SO_EXCLUSIVEADDRUSE, а параметру value — ненулевое значение. Функция WSASetSocketSecurity внутренне вызывает setsockopt с SO_EXCLUSIVEADDRUSE для получения монопольного доступа к порту. Это позволяет гарантировать, что сокет не уязвим к атакам со стороны других приложений, работающих на локальном компьютере.

Параметры безопасности, не заданные с помощью WSASetSocketSecurity , являются производными от политики по умолчанию системы или политики, настроенной администратором. Рекомендуется, чтобы большинство приложений указывали значение SOCKET_SECURITY_PROTOCOL_DEFAULT для перечисления SOCKET_SECURITY_PROTOCOL в элементе SecurityProtocolSOCKET_SECURITY_PROTOCOL , на который указывает параметр SecuritySettings . Это делает приложение нейтральным по отношению к протоколам безопасности и упрощает развертывание в разных системах.

Если параметр 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
Header	ws2tcpip.h
Библиотека	Fwpuclnt.lib
DLL	Fwpuclnt.dll