Função WSASetSocketSecurity (ws2tcpip.h)

Artigo
08/28/2023

A função WSASetSocketSecurity habilita e aplica segurança a um soquete.

Sintaxe

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

Parâmetros

[in] Socket

Um descritor que identifica um soquete no qual as configurações de segurança estão sendo aplicadas.

[in, optional] SecuritySettings

Um ponteiro para uma estrutura SOCKET_SECURITY_SETTINGS que especifica as configurações de segurança a serem aplicadas ao tráfego do soquete. Se esse parâmetro for NULL, as configurações padrão serão aplicadas ao soquete.

[in] SecuritySettingsLen

O tamanho, em bytes, do parâmetro SecuritySettings .

[in, optional] Overlapped

Um ponteiro para uma estrutura WSAOVERLAPPED . Esse parâmetro é ignorado para soquetes não sobrepostos.

[in, optional] CompletionRoutine

Um ponteiro para a rotina de conclusão chamado quando a operação foi concluída. Esse parâmetro é ignorado para soquetes não sobrepostos.

Retornar valor

Se a função obtiver êxito, o valor retornado será zero. Caso contrário, um valor de SOCKET_ERROR é retornado e um código de erro específico pode ser recuperado chamando WSAGetLastError.

Alguns códigos de erro possíveis estão listados abaixo.

Código do erro	Significado
WSAEAFNOSUPPORT	A família de endereços especificada não tem suporte.
WSAEINVAL	Um parâmetro inválido foi passado. Esse erro será retornado se o soquete passado no parâmetro Socket não tiver sido criado com uma família de endereços do AF_INET ou AF_INET6 e um tipo de soquete de SOCK_DGRAM ou SOCK_STREAM. Esse erro também será retornado se a estrutura SOCKET_SECURITY_SETTINGS apontada pelo parâmetro SecuritySettings tiver um valor incorreto.
WSAEISCONN	O soquete está conectado. Essa função não é permitida com um soquete conectado, independentemente de o soquete ser orientado à conexão ou sem conexão.
WSAEMSGSIZE	Um buffer passado era muito pequeno.
WSAENOTSOCK	O descritor passado no parâmetro Socket não é um soquete válido.

Comentários

A principal finalidade da função WSASetSocketSecurity é ativar a segurança de um soquete se ele ainda não estiver habilitado pela política administrativa. Para o IPsec, isso significa que os filtros e políticas IPsec apropriados serão instanciados que serão usados para proteger esse soquete. A função WSASetSocketSecurity também pode ser usada para definir requisitos de segurança específicos para o soquete.

Essa função simplifica a necessidade de chamar a função WSAIoctl com um parâmetro dwIoControlCode definido como SIO_SET_SECURITY.

A função WSASetSocketSecurity pode ser chamada em um parâmetro Socket criado com uma família de endereços de AF_INET ou AF_INET6.

Para um aplicativo cliente que usa soquetes orientados à conexão (protocolo de IPPROTO_TCP), a função WSASetSocketSecurity deve ser chamada antes que a função connect, ConnectEx ou WSAConnect seja chamada. Se a função WSASetSocketSecurity for chamada após a função connect, ConnectEx ou WSAConnect , WSASetSocketSecurity deverá falhar.

Para um aplicativo de servidor que usa soquetes orientados à conexão (protocolo de IPPROTO_TCP), a função WSASetSocketSecurity deve ser chamada antes que a função bind seja chamada. Se a função WSASetSocketSecurity for chamada após a função de associação , WSASetSocketSecurity deverá falhar.

Para soquetes sem conexão (protocolo de IPPROTO_UDP), o aplicativo deve chamar a função WSASetSocketSecurity imediatamente após o retorno da chamada de soquete ou WSASocket .

Os aplicativos de servidor devem chamar a função setsockopt para adquirir acesso exclusivo à porta usada pelo soquete. Isso impede que outros aplicativos usem a mesma porta. A função setsockopt seria chamada com o parâmetro de nível definido como SOL_SOCKET, o parâmetro optname definido como SO_EXCLUSIVEADDRUSE e o parâmetro de valor definido como diferente de zero. A função WSASetSocketSecurity chama internamente o setsockopt com SO_EXCLUSIVEADDRUSE para obter acesso exclusivo à porta. Isso é para garantir que o soquete não esteja vulnerável a ataques de outros aplicativos em execução no computador local.

As configurações de segurança não definidas usando o WSASetSocketSecurity são derivadas da política padrão do sistema ou da política configurada administrativamente. É recomendável que a maioria dos aplicativos especifique um valor de SOCKET_SECURITY_PROTOCOL_DEFAULT para a enumeração SOCKET_SECURITY_PROTOCOL no membro SecurityProtocol do SOCKET_SECURITY_PROTOCOL apontado pelo parâmetro SecuritySettings . Isso torna o aplicativo neutro para protocolos de segurança e permite implantações mais fáceis entre diferentes sistemas.

Quando o parâmetro SecuritySettings aponta para uma estrutura SOCKET_SECURITY_SETTINGS_IPSEC , o membro SecurityProtocol da estrutura deve ser definido como SOCKET_SECURITY_PROTOCOL_IPSEC, não SOCKET_SECURITY_PROTOCOL_DEFAULT.

Um erro será retornado se as condições a seguir não forem atendidas.

A família de endereços do parâmetro Socket deve ser AF_INET ou AF_INET6.
O tipo de soquete deve ser SOCK_STREAM ou SOCK_DGRAM.
O aplicativo deve definir suas configurações de segurança antes de chamar as funções bind, connect, ConnectEx ou WSAConnect .
A função WSASetSocketSecurity só pode ser chamada uma vez por soquete.

Política de IPsec de Soquete Seguro Padrão

Se o parâmetro SecuritySettings estiver definido como NULL e não houver nenhuma outra política IPsec especificada administrativamente no computador, uma política de segurança padrão baseada em IPsec será usada para proteger o tráfego do aplicativo. Algum tipo de credencial de autenticação (um certificado de usuário ou associação de domínio, por exemplo) deve estar presente para que o IPsec tenha êxito com uma política padrão.

A política padrão do IPsec foi projetada para que a segurança IPsec possa ser negociada no maior número possível de cenários.

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

Requisitos


Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ws2tcpip.h
Biblioteca	Fwpuclnt.lib
DLL	Fwpuclnt.dll