WSAImpersonateSocketPeer-Funktion (ws2tcpip.h)

Artikel
08/28/2023

Die WSAImpersonateSocketPeer-Funktion wird verwendet, um die Identität des Sicherheitsprinzipals zu übernehmen, der einem Socketpeer entspricht, um die Autorisierung auf Anwendungsebene durchzuführen.

Syntax

INT WSAAPI WSAImpersonateSocketPeer(
  [in]           SOCKET         Socket,
  [in, optional] const sockaddr *PeerAddr,
  [in]           ULONG          PeerAddrLen
);

Parameter

[in] Socket

Identifiziert den Anwendungssocket.

[in, optional] PeerAddr

Die IP-Adresse des Peers, der identitätswechselt werden soll. Bei verbindungsorientierten Sockets identifiziert der verbundene Socket einen Peer eindeutig. In diesem Fall wird dieser Parameter ignoriert.

[in] PeerAddrLen

Die Größe des PeerAddress-Parameters in Bytes.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert 0. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden.

Einige mögliche Fehlercodes sind unten aufgeführt.

Fehlercode	Bedeutung
WSAEFAULT	Beim Versuch, ein Zeigerargument eines Aufrufs zu verwenden, hat das System einen ungültigen Adresszeiger erkannt. Dieser Fehler wird zurückgegeben, wenn der PeerAddr-Parameter ein NULL-Zeiger war.
WSAEAFNOSUPPORT	Die angegebene Adressfamilie wird nicht unterstützt.
WSAEMSGSIZE	Ein übergebener Puffer war zu klein.
WSAENOTSOCK	Der im Socket-Parameter übergebene Deskriptor ist kein gültiger Socket.

Hinweise

Die WSAImpersonateSocketPeer-Funktion bietet einer Anwendung die Möglichkeit, die Identität des Sicherheitsprinzipals zu übernehmen, der einem Socketpeer entspricht, um eine Autorisierung auf Anwendungsebene durchzuführen. Wenn das Peerbenutzertoken (Identitätswechsel) verfügbar ist, wird es für den Identitätswechsel verwendet, andernfalls wird das Peercomputertoken verwendet. Die WSAImpersonateSocketPeer-Funktion kann nur für blockierende, nicht überlappende Sockets aufgerufen werden. Nach der Durchführung von Autorisierungsprüfungen muss eine Anwendung die WSARevertImpersonation-Funktion aufrufen, um den Identitätswechsel zu beenden.

Bei verbindungsorientierten Sockets sollte die WSAImpersonateSocketPeer-Funktion aufgerufen werden, nachdem eine Verbindung hergestellt wurde. Bei einer Serveranwendung, die verbindungsorientierte Sockets verwendet, sollte WSAImpersonateSocketPeer aufgerufen werden, nachdem die Funktion accept, AcceptEx oder WSAAccept zurückgegeben wurde.

Für verbindungslose Sockets sollte die Anwendung die WSAImpersonateSocketPeer-Funktion sofort aufrufen, nachdem die Funktion recv, recvfrom, WSARecvEx, WSARecvEx, WSARecvFrom oder LPFN_WSARECVMSG (WSARecvMsg) für eine neue Peeradresse zurückgegeben wird.

Die WSAImpersonateSocketPeer-Funktion kann für einen einzelnen Socket mehrmals aufgerufen werden.

Wenn die folgenden Bedingungen nicht erfüllt sind, wird ein Fehler zurückgegeben.

Die Adressfamilie des Socket-Parameters muss entweder AF_INET oder AF_INET6 sein.
Der Sockettyp muss entweder SOCK_STREAM oder SOCK_DGRAM sein.

Die WSARevertImpersonation-Funktion muss aufgerufen werden, um den Identitätswechsel zu beenden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ws2tcpip.h
Bibliothek	fwpuclnt.lib
DLL	Fwpuclnt.dll