Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
The WSAQuerySocketSecurity function queries information about the security applied to a connection on a socket.
Syntax
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
);
Parameters
[in] Socket
A descriptor identifying a socket for which security information is being queried.
[in, optional] SecurityQueryTemplate
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.
[in] SecurityQueryTemplateLen
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.
[out, optional] SecurityQueryInfo
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.
[in, out] SecurityQueryInfoLen
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.
[in, optional] Overlapped
A pointer to a WSAOVERLAPPED structure. This parameter is ignored for non-overlapped sockets.
[in, optional] CompletionRoutine
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 code | Meaning |
|---|---|
| The specified address family is not supported. | |
| 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. | |
| 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. | |
| 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. | |
| 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. | |
| 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
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | ws2tcpip.h |
| Library | Fwpuclnt.lib |
| DLL | Fwpuclnt.dll |
See also
SOCKET_SECURITY_QUERY_TEMPLATE
Using Secure Socket Extensions