Función WSAQuerySocketSecurity (ws2tcpip.h)

Artículo
08/28/2023

La función WSAQuerySocketSecurity consulta información sobre la seguridad aplicada a una conexión en un socket.

Sintaxis

INT WSAAPI WSAQuerySocketSecurity(
  [in]            SOCKET                               Socket,
  [in, optional]  const SOCKET_SECURITY_QUERY_TEMPLATE *SecurityQueryTemplate,
  [in]            ULONG                                SecurityQueryTemplateLen,
  [out, optional] SOCKET_SECURITY_QUERY_INFO           *SecurityQueryInfo,
  [in, out]       ULONG                                *SecurityQueryInfoLen,
  [in, optional]  LPWSAOVERLAPPED                      Overlapped,
  [in, optional]  LPWSAOVERLAPPED_COMPLETION_ROUTINE   CompletionRoutine
);

Parámetros

[in] Socket

Descriptor que identifica un socket para el que se consulta la información de seguridad.

[in, optional] SecurityQueryTemplate

Puntero a una estructura SOCKET_SECURITY_QUERY_TEMPLATE que especifica el tipo de información de consulta que se va a devolver.

Una estructura de SOCKET_SECURITY_QUERY_TEMPLATE a la que apunta este parámetro puede contener ceros para que todos los miembros soliciten información de seguridad predeterminada. Si la devolución es correcta, solo el miembro Flags de la SOCKET_SECURITY_QUERY_INFO se establecerá en el parámetro SecurityQueryInfo devuelto.

Este parámetro puede ser un puntero NULL si el parámetro Socket se creó con un protocolo de IPPROTO_TCP. En este caso, la información devuelta es la misma que si se pasó una estructura de SOCKET_SECURITY_QUERY_TEMPLATE con todos los valores establecidos en cero. Este parámetro debe especificarse para un socket con protocolo de IPPROTO_TCP si se requiere más información de seguridad predeterminada.

Si la estructura de SOCKET_SECURITY_QUERY_TEMPLATE se especifica con el miembro PeerTokenAccessMask no especificado (establecido en cero), la función WSAQuerySocketSecurity no devolverá los miembros PeerApplicationAccessTokenHandle y PeerMachineAccessTokenHandle en la estructura SOCKET_SECURITY_QUERY_INFO .

Si se creó un parámetro Socket con un protocolo no igual a IPPROTO_TCP, se debe especificar el parámetro SecurityQueryTemplate . En estos casos, el miembro PeerAddress de la estructura SOCKET_SECURITY_QUERY_TEMPLATE debe especificar una familia de direcciones de AF_INET o AF_INET6 junto con la dirección IP del mismo nivel y el número de puerto.

[in] SecurityQueryTemplateLen

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

Este parámetro puede ser cero si el parámetro Socket se creó con un protocolo de IPPROTO_TCP. De lo contrario, este parámetro debe ser el tamaño de una estructura SOCKET_SECURITY_QUERY_TEMPLATE .

[out, optional] SecurityQueryInfo

Puntero a un búfer que recibirá una estructura SOCKET_SECURITY_QUERY_INFO que contiene la información consultada. Este valor se puede establecer en NULL para consultar el tamaño del búfer de salida.

[in, out] SecurityQueryInfoLen

En la entrada, un puntero al tamaño, en bytes, del parámetro SecurityQueryInfo . Si el búfer es demasiado pequeño para recibir la información consultada, la llamada devolverá SOCKET_ERROR y el número de bytes necesarios para devolver la información consultada se establecerá en el valor al que apunta este parámetro. En una llamada correcta, se devuelve el número de bytes copiados.

[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 mediante una llamada 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.
WSAECONNRESET	En el caso de un socket de flujo, el circuito virtual se restableció por el lado remoto. La aplicación debería cerrar el socket porque ya no se puede usar. En el caso de un socket de datagrama UDP, este error indicaría que una operación de envío anterior dio lugar a un mensaje icMP "Puerto inaccesible".
WSAEFAULT	El sistema detectó una dirección de puntero no válida al intentar usar un parámetro . Este error se devuelve si el parámetro SecurityQueryInfoLen 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 de la AF_INET o AF_INET6 y un tipo de socket de SOCK_DGRAM o SOCK_STREAM.
WSAEMSGSIZE	Un búfer pasado era demasiado pequeño. Este error se devuelve para un parámetro Socket cuando el protocolo no se IPPROTO_TCP si el parámetro SecurityQueryInfo es un puntero NULL o el parámetro SecurityQueryTemplateLen es menor que el tamaño de una estructura de SOCKET_SECURITY_QUERY_TEMPLATE .
WSAENOTSOCK	El descriptor pasado en el parámetro Socket no es un socket válido.

Comentarios

La función WSAQuerySocketSecurity proporciona un método para consultar la configuración de seguridad actual en un socket. Una vez establecida una conexión, la función WSAQuerySocketSecurity permite a una aplicación consultar las propiedades de seguridad de la conexión, lo que puede incluir información sobre los tokens de acceso del mismo nivel.

En el caso de los sockets orientados a la conexión, se prefiere llamar a la función WSAQuerySocketSecurity inmediatamente después de establecer una conexión. En el caso de los sockets sin conexión, se prefiere llamar a la función WSAQuerySocketSecurity inmediatamente después de que los datos se envíen a una nueva dirección del mismo nivel o se reciban de una nueva dirección del mismo nivel. La función WSAQuerySocketSecurity se puede llamar varias veces en un único socket.

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

Se puede llamar a la función WSAQuerySocketSecurity en un parámetro Socket creado con una familia de direcciones de AF_INET o AF_INET6.

Si el parámetro Socket se creó con un protocolo de IPPROTO_TCP, el parámetro SecurityQueryTemplate puede ser NULL y el parámetro SecurityQueryTemplateLen puede ser cero. De lo contrario, el parámetro SecurityQueryTemplate debe apuntar a una estructura de SOCKET_SECURITY_QUERY_TEMPLATE .

Para una aplicación cliente mediante sockets orientados a la conexión (socket creado con un protocolo de IPPROTO_TCP), se debe llamar a la función WSAQuerySocketSecurity después de que se devuelva la función connect, ConnectEx o WSAConnect . Para una aplicación de servidor mediante sockets orientados a la conexión (protocolo de IPPROTO_TCP), se debe llamar a la función WSAQuerySocketSecurity después de que se devuelva la función accept, AcceptEx o WSAAccept .

Para sockets sin conexión (socket creado con un protocolo de IPPROTO_UDP), la aplicación debe llamar a la función WSAQuerySocketSecurity inmediatamente después de que WSASendTo o WSARecvFrom devuelva una nueva dirección del mismo nivel.

Si no se cumplen las condiciones siguientes, se devolverá un error.

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

Requisito	Value
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