Função WSASetSocketPeerTargetName (ws2tcpip.h)

Artigo
08/28/2023

A função WSASetSocketPeerTargetName é usada para especificar o SPN (nome de destino par) que corresponde a um endereço IP par. Esse nome de destino deve ser especificado por aplicativos cliente para identificar com segurança o par que deve ser autenticado.

Sintaxe

INT WSAAPI WSASetSocketPeerTargetName(
  [in]           SOCKET                             Socket,
  [in]           const SOCKET_PEER_TARGET_NAME      *PeerTargetName,
  [in]           ULONG                              PeerTargetNameLen,
  [in, optional] LPWSAOVERLAPPED                    Overlapped,
  [in, optional] LPWSAOVERLAPPED_COMPLETION_ROUTINE CompletionRoutine
);

Parâmetros

[in] Socket

Um descritor que identifica um soquete no qual o nome de destino par está sendo atribuído.

[in] PeerTargetName

Um ponteiro para uma estrutura SOCKET_PEER_TARGET_NAME que define o nome de destino do par.

[in] PeerTargetNameLen

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

[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.

Valor retornado

Se a função obtiver êxito, o valor retornado será zero. Caso contrário, um valor de SOCKET_ERROR será retornado e um código de erro específico poderá 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.
WSAEFAULT	O sistema detectou um ponteiro de endereço inválido ao tentar usar um argumento de ponteiro de uma chamada. Esse erro será retornado se o parâmetro PeerTargetName for um ponteiro NULL .
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 para um soquete sem conexão se o endereço IP e a porta forem zero no membro PeerAddress da estrutura SOCKET_PEER_TARGET_NAME apontada pelo parâmetro PeerTargetName .
WSAEISCONN	O soquete está conectado. Essa função não é permitida com um soquete conectado, independentemente de o soquete ser orientado para 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 função WSASetSocketPeerTargetName fornece um método para especificar o nome de destino que corresponde a uma entidade de segurança par. Essa função deve ser usada por um aplicativo cliente para identificar o par que deve ser autenticado. Um aplicativo cliente deve especificar o nome de destino par para evitar ataques man-in-the-middle confiáveis. Para soquetes sem conexão, um aplicativo pode chamar a função WSASetSocketPeerTargetName várias vezes para especificar nomes de destino diferentes para endereços IP de pares diferentes.

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

Para soquetes orientados à conexão, a função WSASetSocketPeerTargetName deve ser chamada antes de WSAConnect. Para soquetes sem conexão, essa função deve ser chamada antes do WSAConnect ou antes da primeira chamada WSASendTo direcionada para o endereço par.

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.

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