Export (0) Print
Expand All
Expand Minimize

WSAImpersonateSocketPeer function

The WSAImpersonateSocketPeer function is used to impersonate the security principal corresponding to a socket peer in order to perform application-level authorization.

Syntax


int WSAImpersonateSocketPeer(
  _In_      SOCKET Socket,
  _In_opt_  const sockaddr PeerAddress,
  _In_      ULONG peerAddressLen
);

Parameters

Socket [in]

Identifies the application socket.

PeerAddress [in, optional]

The IP address of the peer to be impersonated. For connection-oriented sockets, the connected socket uniquely identifies a peer. In this case, this parameter is ignored.

peerAddressLen [in]

The size, in bytes, of the PeerAddress parameter.

Return value

If the function succeeds, the return value is 0. 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
WSAEFAULT

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

WSAEAFNOSUPPORT

The specified address family is not supported.

WSAEMSGSIZE

A buffer passed was too small.

WSAENOTSOCK

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

 

Remarks

The WSAImpersonateSocketPeer function provides an application the ability to impersonate the security principal corresponding to a socket peer in order to perform application-level authorization. If peer user (impersonation) token is available then it will be used for impersonation, otherwise the peer computer token will be used. The WSAImpersonateSocketPeer function can be called only for blocking, non-overlapped sockets. After performing any authorization checks, an application must call the WSARevertImpersonation function to terminate the impersonation.

For connection-oriented sockets, the WSAImpersonateSocketPeer function should be called after a connection is established. For a server application using connection-oriented sockets, the WSAImpersonateSocketPeer should be called after the accept, AcceptEx, or WSAAccept function returns.

For connectionless sockets, the application should call the WSAImpersonateSocketPeer function immediately after the recv, recvfrom, WSARecv, WSARecvEx, WSARecvFrom, or WSARecvMsg function returns for a new peer address.

The WSAImpersonateSocketPeer function can be called multiple times for a single socket.

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.

The WSARevertImpersonation function must be called to end the impersonation.

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

accept
AcceptEx
recv
recvfrom
Using Secure Socket Extensions
Windows Filtering Platform
Windows Filtering Platform API Functions
Winsock Secure Socket Extensions
WSAAccept
WSADeleteSocketPeerTargetName
WSAQuerySocketSecurity
WSARecv
WSARecvEx
WSARecvFrom
WSARecvMsg
WSARevertImpersonation
WSASetSocketPeerTargetName
WSASetSocketSecurity

 

 

Community Additions

ADD
Show:
© 2014 Microsoft