Función WSASetSocketPeerTargetName (ws2tcpip.h)

Artículo
08/28/2023

La función WSASetSocketPeerTargetName se usa para especificar el nombre de destino del mismo nivel (SPN) que corresponde a una dirección IP del mismo nivel. Las aplicaciones cliente especifican este nombre de destino para identificar de forma segura el elemento del mismo nivel que se debe autenticar.

Sintaxis

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

Descriptor que identifica un socket en el que se asigna el nombre de destino del mismo nivel.

[in] PeerTargetName

Puntero a una estructura de SOCKET_PEER_TARGET_NAME que define el nombre de destino del mismo nivel.

[in] PeerTargetNameLen

Tamaño, en bytes, del parámetro PeerTargetName .

[in, optional] Overlapped

Puntero a una estructura WSAOVERLAPPED . Este parámetro se omite para sockets no superpuestos.

[in, optional] CompletionRoutine

Puntero a la rutina de finalización a la que se llama cuando se ha completado la operación. Este parámetro se omite para sockets no superpuestos.

Valor devuelto

Si la función es correcta, el valor devuelto es cero. De lo contrario, se devuelve un valor de SOCKET_ERROR y se puede recuperar un código de error específico llamando a WSAGetLastError.

A continuación se enumeran algunos códigos de error posibles.

Código de error	Significado
WSAEAFNOSUPPORT	La familia de direcciones especificada no se admite.
WSAEFAULT	El sistema detectó un puntero de dirección no válido al intentar usar un argumento de puntero de una llamada. Este error se devuelve si el parámetro PeerTargetName era un puntero NULL .
WSAEINVAL	Se pasó un parámetro no válido. Este error se devuelve si el socket pasado en el parámetro Socket no se creó con una familia de direcciones del AF_INET o AF_INET6 y un tipo de socket de SOCK_DGRAM o SOCK_STREAM. Este error también se devuelve para un socket sin conexión si la dirección IP y el puerto son cero en el miembro PeerAddress de la estructura SOCKET_PEER_TARGET_NAME apuntada por el parámetro PeerTargetName .
WSAEISCONN	El socket está conectado. Esta función no se permite con un socket conectado, ya sea que el socket esté orientado a la conexión o sin conexión.
WSAEMSGSIZE	Un búfer pasado era demasiado pequeño.
WSAENOTSOCK	El descriptor pasado en el parámetro Socket no es un socket válido.

Observaciones

La función WSASetSocketPeerTargetName proporciona un método para especificar el nombre de destino que corresponde a una entidad de seguridad del mismo nivel. Esta función está pensada para que la use una aplicación cliente para identificar el elemento del mismo nivel que se debe autenticar. Una aplicación cliente debe especificar el nombre de destino del mismo nivel para evitar ataques de tipo "man in the middle" de confianza. En el caso de los sockets sin conexión, una aplicación puede llamar a la función WSASetSocketPeerTargetName varias veces para especificar nombres de destino diferentes para diferentes direcciones IP del mismo nivel.

Esta función simplifica la necesidad de llamar a la función WSAIoctl con un parámetro dwIoControlCode establecido en SIO_SET_PEER_TARGET_NAME.

Para los sockets orientados a la conexión, se debe llamar a la función WSASetSocketPeerTargetName antes de WSAConnect. En el caso de los sockets sin conexión, se debe llamar a esta función antes de WSAConnect o antes de la primera llamada de WSASendTo dirigida a la dirección del mismo nivel.

Se devolverá un error si no se cumplen las condiciones siguientes.

La familia de direcciones del parámetro Socket debe ser AF_INET o AF_INET6.
El tipo de socket debe ser SOCK_STREAM o SOCK_DGRAM.

Requisitos


Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ws2tcpip.h
Library	Fwpuclnt.lib
Archivo DLL	Fwpuclnt.dll