Funzione WSASetSocketSecurity (ws2tcpip.h)

Articolo
08/28/2023

La funzione WSASetSocketSecurity abilita e applica la sicurezza per un socket.

Sintassi

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

Parametri

[in] Socket

Descrittore che identifica un socket in cui vengono applicate le impostazioni di sicurezza.

[in, optional] SecuritySettings

Puntatore a una struttura SOCKET_SECURITY_SETTINGS che specifica le impostazioni di sicurezza da applicare al traffico del socket. Se questo parametro è NULL, le impostazioni predefinite verranno applicate al socket.

[in] SecuritySettingsLen

Dimensioni, in byte, del parametro SecuritySettings .

[in, optional] Overlapped

Puntatore a una struttura WSAOVERLAPPED . Questo parametro viene ignorato per socket non sovrapposti.

[in, optional] CompletionRoutine

Puntatore alla routine di completamento chiamata al termine dell'operazione. Questo parametro viene ignorato per socket non sovrapposti.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è zero. In caso contrario, viene restituito un valore di SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.

Di seguito sono elencati alcuni codici di errore possibili.

Codice di errore	Significato
WSAEAFNOSUPPORT	La famiglia di indirizzi specificata non è supportata.
WSAEINVAL	È stato passato un parametro non valido. Questo errore viene restituito se il socket passato nel parametro Socket non è stato creato con una famiglia di indirizzi del AF_INETo AF_INET6 e un tipo di socket di SOCK_DGRAM o SOCK_STREAM. Questo errore viene restituito anche se la struttura SOCKET_SECURITY_SETTINGS puntata dal parametro SecuritySettings ha un valore non corretto.
WSAEISCONN	Il socket è connesso. Questa funzione non è consentita con un socket connesso, indipendentemente dal fatto che il socket sia orientato alla connessione o senza connessione.
WSAEMSGSIZE	Un buffer passato era troppo piccolo.
WSAENOTSOCK	Il descrittore passato nel parametro Socket non è un socket valido.

Commenti

Lo scopo principale della funzione WSASetSocketSecurity consiste nell'attivare la sicurezza per un socket se non è già abilitato dai criteri amministrativi. Per IPsec, ciò significa che i filtri e i criteri IPsec appropriati verranno create per creare un'istanza che verrà usata per proteggere questo socket. La funzione WSASetSocketSecurity può essere usata anche per impostare requisiti di sicurezza specifici per il socket.

Questa funzione semplifica la chiamata alla funzione WSAIoctl con un parametro dwIoControlCode impostato su SIO_SET_SECURITY.

La funzione WSASetSocketSecurity può essere chiamata su un parametro Socket creato con una famiglia di indirizzi di AF_INET o AF_INET6.

Per un'applicazione client che usa socket orientati alla connessione (protocollo di IPPROTO_TCP), la funzione WSASetSocketSecurity deve essere chiamata prima che venga chiamata la funzione connect, ConnectEx o WSAConnect . Se la funzione WSASetSocketSecurity viene chiamata dopo la connessione, ConnectEx o la funzione WSAConnect,WSASetSocketSecurity deve avere esito negativo.

Per un'applicazione server che usa socket orientati alla connessione (protocollo di IPPROTO_TCP), la funzione WSASetSocketSecurity deve essere chiamata prima che venga chiamata la funzione di associazione . Se la funzione WSASetSocketSecurity viene chiamata dopo la funzione di associazione , WSASetSocketSecurity deve avere esito negativo.

Per i socket senza connessione (protocollo di IPPROTO_UDP), l'applicazione deve chiamare la funzione WSASetSocketSecurity immediatamente dopo la restituzione della chiamata socket o WSASocket .

Le applicazioni server devono chiamare la funzione setockopt per acquisire l'accesso esclusivo alla porta usata dal socket. Ciò impedisce ad altre applicazioni di usare la stessa porta. La funzione setockopt verrà chiamata con il parametro di livello impostato su SOL_SOCKET, il parametro optname impostato su SO_EXCLUSIVEADDRUSE e il parametro valore impostato su non zero. La funzione WSASetSocketSecurity chiama internamente il setockopt con SO_EXCLUSIVEADDRUSE per ottenere l'accesso esclusivo alla porta. Si tratta di garantire che il socket non sia vulnerabile agli attacchi da altre applicazioni in esecuzione nel computer locale.

Le impostazioni di sicurezza non impostate usando WSASetSocketSecurity sono derivate dai criteri predefiniti del sistema o dai criteri configurati in modo amministrativo. È consigliabile che la maggior parte delle applicazioni specifichi un valore di SOCKET_SECURITY_PROTOCOL_DEFAULT per l'enumerazione SOCKET_SECURITY_PROTOCOL nel membro SecurityProtocol del SOCKET_SECURITY_PROTOCOL a cui punta il parametro SecuritySettings . Ciò rende l'applicazione neutrale ai protocolli di sicurezza e consente distribuzioni più semplici tra sistemi diversi.

Quando il parametro SecuritySettings punta a una struttura SOCKET_SECURITY_SETTINGS_IPSEC , il membro SecurityProtocol della struttura deve essere impostato su SOCKET_SECURITY_PROTOCOL_IPSEC, non SOCKET_SECURITY_PROTOCOL_DEFAULT.

Se le condizioni seguenti non vengono soddisfatte, verrà restituito un errore.

La famiglia di indirizzi del parametro Socket deve essere AF_INET o AF_INET6.
Il tipo di socket deve essere SOCK_STREAM o SOCK_DGRAM.
L'applicazione deve impostare le impostazioni di sicurezza prima di chiamare le funzioni bind, connect, ConnectEx o WSAConnect.
La funzione WSASetSocketSecurity può essere chiamata una sola volta per socket.

Criterio IPsec secure socket predefinito

Se il parametro SecuritySettings è impostato su NULL e non esiste alcun altro criterio IPsec specificato in modo amministrativo nel computer, verrà usato un criterio di sicurezza predefinito basato su IPsec per proteggere il traffico dell'applicazione. Alcuni tipi di credenziali di autenticazione (un certificato utente o un'appartenenza al dominio, ad esempio) devono essere presenti per IPsec per avere esito positivo con un criterio predefinito.

I criteri IPsec predefiniti sono stati progettati in modo che la sicurezza IPsec possa essere negoziata nel maggior numero possibile di scenari.

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

Requisiti


Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ws2tcpip.h
Libreria	Fwpuclnt.lib
DLL	Fwpuclnt.dll