Export (0) Print
Expand All
Expand Minimize

WSAQuerySocketSecurity function

The WSAQuerySocketSecurity function queries information about the security applied to a connection on a socket.

Syntax


int WSAAPI WSAQuerySocketSecurity(
  _In_       SOCKET Socket,
  _In_opt_   const SOCKET_SECURITY_QUERY_TEMPLATE *SecurityQueryTemplate,
  _In_       ULONG SecurityQueryTemplateLen,
  _Out_opt_  SOCKET_SECURITY_QUERY_INFO *SecurityQueryInfo,
  _Inout_    ULONG *SecurityQueryInfoLen,
  _In_opt_   LPWSAOVERLAPPED Overlapped,
  _In_opt_   LPWSAOVERLAPPED_COMPLETION_ROUTINE CompletionRoutine
);

Parameters

Socket [in]

A descriptor identifying a socket for which security information is being queried.

SecurityQueryTemplate [in, optional]

A pointer to a SOCKET_SECURITY_QUERY_TEMPLATE structure that specifies the type of query information to return.

A SOCKET_SECURITY_QUERY_TEMPLATE structure pointed to by this parameter may contain zeroes for all members to request default security information. On successful return, only the Flags member in the SOCKET_SECURITY_QUERY_INFO will be set in the returned SecurityQueryInfo parameter.

This parameter may be a NULL pointer if the Socket parameter was created with a protocol of IPPROTO_TCP. In this case, the information returned is the same as if a SOCKET_SECURITY_QUERY_TEMPLATE structure with all values set to zero was passed. This parameter should be specified for a socket with protocol of IPPROTO_TCP if more than the default security information is required.

If the SOCKET_SECURITY_QUERY_TEMPLATE structure is specified with the PeerTokenAccessMask member not specified (set to zero), then the WSAQuerySocketSecurity function will not return the PeerApplicationAccessTokenHandle and PeerMachineAccessTokenHandle members in the SOCKET_SECURITY_QUERY_INFO structure.

If a Socket parameter was created with a protocol not equal to IPPROTO_TCP, the SecurityQueryTemplate parameter must be specified. In these cases, the PeerAddress member of the SOCKET_SECURITY_QUERY_TEMPLATE structure must specify an address family of AF_INET or AF_INET6 along with peer IP address and port number.

SecurityQueryTemplateLen [in]

The size, in bytes, of the SecurityQueryTemplate parameter.

This parameter may be a zero if the Socket parameter was created with a protocol of IPPROTO_TCP. Otherwise, this parameter must be the size of a SOCKET_SECURITY_QUERY_TEMPLATE structure.

SecurityQueryInfo [out, optional]

A pointer to a buffer that will receive a SOCKET_SECURITY_QUERY_INFO structure containing the information queried. This value can be set to NULL to query the size of the output buffer.

SecurityQueryInfoLen [in, out]

On input, a pointer to the size, in bytes, of the SecurityQueryInfo parameter. If the buffer is too small to receive the queried information, the call will return SOCKET_ERROR, and the number of bytes needed to return the queried information will be set in the value pointed to by this parameter. On a successful call, the number of bytes copied is returned.

Overlapped [in, optional]

A pointer to a WSAOVERLAPPED structure. This parameter is ignored for non-overlapped sockets.

CompletionRoutine [in, optional]

A pointer to the completion routine called when the operation has been completed. This parameter is ignored for non-overlapped sockets.

Return value

If the function succeeds, the return value is zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Some possible error codes are listed below.

Error codeMeaning
WSAEAFNOSUPPORT

The specified address family is not supported.

WSAECONNRESET

For a stream socket, the virtual circuit was reset by the remote side. The application should close the socket as it is no longer usable. For a UDP datagram socket, this error would indicate that a previous send operation resulted in an ICMP "Port Unreachable" message.

WSAEFAULT

The system detected an invalid pointer address in attempting to use a parameter. This error is returned if the SecurityQueryInfoLen parameter was a NULL pointer.

WSAEINVAL

An invalid parameter was passed. This error is returned if the socket passed in the Socket parameter was not created with an address family of the AF_INET or AF_INET6 and a socket type of SOCK_DGRAM or SOCK_STREAM.

WSAEMSGSIZE

A buffer passed was too small. This error is returned for a Socket parameter when the protocol was not IPPROTO_TCP if the SecurityQueryInfo parameter is a NULL pointer or the SecurityQueryTemplateLen parameter is less than the size of a SOCKET_SECURITY_QUERY_TEMPLATE structure.

WSAENOTSOCK

The descriptor passed in the Socket parameter is not a valid socket.

 

Remarks

The WSAQuerySocketSecurity function provides a method to query the current security settings on a socket. After a connection is established, the WSAQuerySocketSecurity function allows an application to query the security properties of the connection, which can include information on peer access tokens.

For connection-oriented sockets, it is preferred to call the WSAQuerySocketSecurity function immediately after a connection is established. For connectionless sockets, it is preferred to call the WSAQuerySocketSecurity function immediately after data is sent to a new peer address or received from a new peer address. The WSAQuerySocketSecurity function can be called multiple times on a single socket.

This function simplifies having to call the WSAIoctl function with a dwIoControlCode parameter set to SIO_QUERY_SECURITY.

The WSAQuerySocketSecurity function may be called on a Socket parameter created with an address family of AF_INET or AF_INET6.

If the Socket parameter was created with a protocol of IPPROTO_TCP, the SecurityQueryTemplate parameter may be NULL and the SecurityQueryTemplateLen parameter may be zero. Otherwise, the SecurityQueryTemplate parameter must point to a SOCKET_SECURITY_QUERY_TEMPLATE structure.

For a client application using connection-oriented sockets (socket created with a protocol of IPPROTO_TCP), the WSAQuerySocketSecurity function should be called after the connect, ConnectEx, or WSAConnect function returns. For a server application using connection-oriented sockets (protocol of IPPROTO_TCP), the WSAQuerySocketSecurity function should be called after the accept, AcceptEx, or WSAAccept function returns.

For connectionless sockets (socket created with a protocol of IPPROTO_UDP), the application should call the WSAQuerySocketSecurity function immediately after WSASendTo or WSARecvFrom call returns for a new peer address.

An error will be returned if the following conditions are not met.

  • The address family of the Socket parameter must be either AF_INET or AF_INET6.
  • The socket type must be either SOCK_STREAM or SOCK_DGRAM.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Ws2tcpip.h

Library

Fwpuclnt.lib

DLL

Fwpuclnt.dll

See also

SOCKET_SECURITY_QUERY_INFO
SOCKET_SECURITY_QUERY_TEMPLATE
Using Secure Socket Extensions
Windows Filtering Platform
Windows Filtering Platform API Functions
Winsock Secure Socket Extensions
WSADeleteSocketPeerTargetName
WSAImpersonateSocketPeer
WSARevertImpersonation
WSASetSocketPeerTargetName
WSASetSocketSecurity

 

 

Community Additions

ADD
Show:
© 2014 Microsoft