SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS-Steuerelementcode
BESCHREIBUNG
Der SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS Steuercode ruft den Umleitungsdatensatz für die akzeptierte TCP/IP-Verbindung zur Verwendung durch einen WFP-Umleitungsdienst (Windows Filtering Platform) ab.
Um diesen Vorgang auszuführen, rufen Sie die Funktion WSAIoctl oder WSPIoctl mit den folgenden Parametern auf.
int WSAIoctl(
(socket) s, // descriptor identifying a socket
SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS, // dwIoControlCode
NULL, // lpvInBuffer
0, // cbInBuffer
(LPVOID) lpvOutBuffer, // output buffer
(DWORD) cbOutBuffer, // size of output buffer
(LPDWORD) lpcbBytesReturned, // number of bytes returned
(LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
(LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine, // completion routine
);
int WSAIoctl(
(socket) s, // descriptor identifying a socket
SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS, // dwIoControlCode
NULL, // lpvInBuffer
0, // cbInBuffer
(LPVOID) lpvOutBuffer, // output buffer
(DWORD) cbOutBuffer, // size of output buffer
(LPDWORD) lpcbBytesReturned, // number of bytes returned
(LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
(LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine, // completion routine
);
Parameter
s
Ein Deskriptor, der einen Socket identifiziert.
dwIoControlCode
Der Steuerelementcode für den Vorgang. Verwenden Sie für diesen Vorgang SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS .
lpvInBuffer
Ein Zeiger auf den Eingabepuffer. Dieser Parameter wird für diesen Vorgang nicht verwendet.
cbInBuffer
Die Größe des Eingabepuffers in Bytes. Dieser Parameter wird für diesen Vorgang nicht verwendet.
lpvOutBuffer
Ein Zeiger auf den Ausgabepuffer. Dieser Parameter sollte auf einen ULONG-Datentyp verweisen, wenn die Parameter lpOverlapped und lpCompletionRoutineNULL sind.
cbOutBuffer
Die Größe des Ausgabepuffers in Bytes. Dieser Parameter muss mindestens die Größe eines ULONG-Datentyps aufweisen.
lpcbBytesReturned
Ein Zeiger auf eine Variable, die die Größe der im Ausgabepuffer gespeicherten Daten in Bytes empfängt.
Wenn der Ausgabepuffer zu klein ist, schlägt der Aufruf fehl, WSAGetLastError gibt WSAEINVAL zurück, und der parameter lpcbBytesReturned verweist auf den DWORD-Wert 0.
Wenn lpOverlappedNULL ist, kann der DWORD-Wert , auf den der lpcbBytesReturned-Parameter verweist, der bei einem erfolgreichen Aufruf zurückgegeben wird, nicht null sein.
Wenn der lpOverlapped-Parameter für überlappende Sockets nicht NULL ist, werden Vorgänge initiiert, die nicht sofort abgeschlossen werden können, und der Abschluss wird zu einem späteren Zeitpunkt angezeigt. Der DWORD-Wert , auf den der zurückgegebene Parameter lpcbBytesReturned verweist, kann null sein, da die Größe der gespeicherten Daten erst bestimmt werden kann, wenn der überlappende Vorgang abgeschlossen ist. Der endgültige Abschluss status kann abgerufen werden, wenn die entsprechende Vervollständigungsmethode signalisiert wird, wenn der Vorgang abgeschlossen ist.
lpvOverlapped
Ein Zeiger auf eine WSAOVERLAPPED-Struktur .
Wenn Socket s ohne das überlappende Attribut erstellt wurde, wird der lpOverlapped-Parameter ignoriert.
Wenn s mit dem überlappenden Attribut geöffnet wurde und der lpOverlapped-Parameter nicht NULL ist, wird der Vorgang als überlappender (asynchroner) Vorgang ausgeführt. In diesem Fall muss der lpOverlapped-Parameter auf eine gültige WSAOVERLAPPED-Struktur verweisen.
Bei überlappenden Vorgängen wird die WSAIoctl - oder WSPIoctl-Funktion sofort zurückgegeben, und die entsprechende Abschlussmethode wird nach Abschluss des Vorgangs signalisiert. Andernfalls wird die Funktion erst zurückgegeben, wenn der Vorgang abgeschlossen wurde oder ein Fehler auftritt.
lpCompletionRoutine
Typ: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Ein Zeiger auf die Abschlussroutine, die aufgerufen wird, wenn der Vorgang abgeschlossen wurde (bei nicht überlappenden Sockets ignoriert).
lpThreadId
Ein Zeiger auf eine WSATHREADID-Struktur , die vom Anbieter in einem nachfolgenden Aufruf von WPUQueueApc verwendet werden soll. Der Anbieter sollte die referenzierte WSATHREADID-Struktur (nicht den Zeiger auf dieselbe) speichern, bis die WPUQueueApc-Funktion zurückgegeben wird.
Hinweis Dieser Parameter gilt nur für die WSPIoctl-Funktion .
lpErrno
Ein Zeiger auf den Fehlercode.
Hinweis Dieser Parameter gilt nur für die WSPIoctl-Funktion .
Rückgabewert
Wenn der Vorgang erfolgreich abgeschlossen wird, gibt die WSAIoctl - oder WSPIoctl-Funktion null zurück.
Wenn der Vorgang fehlschlägt oder aussteht, gibt die WSAIoctl - oder WSPIoctl-FunktionSOCKET_ERROR zurück. Rufen Sie WSAGetLastError auf, um erweiterte Fehlerinformationen zu erhalten.
| Fehlercode | Bedeutung |
|---|---|
| ERROR_INSUFFICIENT_BUFFER | Der an einen Systemaufruf übergebene Datenbereich ist zu klein. Dieser Fehler wird zurückgegeben, wenn der Puffer, auf den der Parameter lpvOutBuffer verweist, mit einer Puffergröße, die im cbOutBuffer-Parameter übergeben wird, zu klein ist. Die erforderliche Puffergröße wird im lpcbBytesReturned-Parameter zurückgegeben. |
| WSA_IO_PENDING | Ein überlappender Vorgang wurde erfolgreich initiiert, und der Abschluss wird zu einem späteren Zeitpunkt angezeigt. |
| WSA_OPERATION_ABORTED | Ein überlappender Vorgang wurde aufgrund des Schließens des Sockets oder der Ausführung des SIO_FLUSH IOCTL-Befehls abgebrochen. |
| WSAEFAULT | Die Parameter lpvOutBuffer, lpcbBytesReturned, lpOverlapped oder lpCompletionRoutine sind nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten. |
| WSAEINPROGRESS | Die Funktion wird aufgerufen, wenn ein Rückruf ausgeführt wird. |
| WSAEINTR | Ein blockierende Vorgang wurde unterbrochen. |
| WSAEINVAL | Der dwIoControlCode-Parameter ist kein gültiger Befehl, oder ein angegebener Eingabeparameter ist nicht akzeptabel, oder der Befehl gilt nicht für den angegebenen Sockettyp. Dieser Fehler wird zurückgegeben, wenn der cbOutBuffer-Parameter kleiner als die Größe eines ULONG-Datentyps ist. |
| WSAENETDOWN | Fehler beim Netzwerksubsystem. |
| WSAENOPROTOOPT | Die Socketoption wird im angegebenen Protokoll nicht unterstützt. |
| WSAENOTCONN | Der Socket s ist nicht verbunden. |
| WSAENOTSOCK | Der Deskriptor s ist kein Socket. |
| WSAEOPNOTSUPP | Der angegebene IOCTL-Befehl wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn die SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL vom Transportanbieter nicht unterstützt wird. |
Bemerkungen
Die SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL wird unter Windows 8 und Windows Server 2012 und höheren Versionen des Betriebssystems unterstützt.
WFP ermöglicht den Zugriff auf den TCP/IP-Paketverarbeitungspfad, wobei ausgehende und eingehende Pakete untersucht oder geändert werden können, bevor sie weiter verarbeitet werden können. Durch Die Nutzung des TCP/IP-Verarbeitungspfads können unabhängige Softwarehersteller (ISVs) leichter Firewalls, Antivirensoftware, Diagnosesoftware und andere Arten von Anwendungen und Diensten erstellen. WFP stellt Komponenten für den Benutzermodus und den Kernelmodus bereit, sodass ISVs von Drittanbietern an den Filterentscheidungen teilnehmen können, die auf mehreren Ebenen im TCP/IP-Protokollstapel und im gesamten Betriebssystem stattfinden. Das Feature "WFP-Verbindungsumleitung" ermöglicht es einem WFP-Callout-Kerneltreiber, eine Verbindung lokal an einen Benutzermodusprozess umzuleiten, die Inhaltsüberprüfung im Benutzermodus durchzuführen und den überprüften Inhalt über eine andere Verbindung an das ursprüngliche Ziel weiterzuleiten.
Die SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL und mehrere andere verwandte IOCTLS sind Benutzermoduskomponenten, die verwendet werden, um es mehreren WFP-basierten Verbindungsproxyanwendungen zu ermöglichen, denselben Datenverkehrsfluss auf kooperative Weise zu untersuchen. Jeder Inspektions-Agent kann den Netzwerkdatenverkehr, der bereits von einem anderen Inspektions-Agent überprüft wurde, sicher erneut überprüfen. Wenn mehrere Proxys vorhanden sind (z. B. von verschiedenen ISVs entwickelt), könnte die Verbindung, die von einem Proxy für die Kommunikation mit dem endigen Ziel verwendet wird, wiederum von einem zweiten Proxy umgeleitet werden, und diese neue Verbindung könnte wieder vom ursprünglichen Proxy umgeleitet werden. Ohne Verbindungsnachverfolgung erreicht die ursprüngliche Verbindung möglicherweise nie ihr endgültiges Ziel, da sie in einer endlosen Proxyschleife hängen bleibt.
Die SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL wird verwendet, um eine nachzuverfolgende Verbindung für umgeleitete Socketverbindungen bereitzustellen. Dieses WFP-Feature erleichtert die Nachverfolgung von Umleitungsdatensätzen von der anfänglichen Umleitung einer Verbindung bis zur endgültigen Verbindung mit dem Ziel.
Die SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL wird von einem WFP-basierten Umleitungsdienst verwendet, um den Umleitungsdatensatz von der akzeptierten TCP/IP-Paketverbindung (z. B. dem verbundenen Socket für einen TCP-Socket oder einem UDP-Socket) abzurufen, der von der zugehörigen Kernelmodus-Legende, die auf ALE_CONNECT_REDIRECT Ebenen in einem Kernelmodustreiber registriert ist, an ihn umgeleitet wird. Die SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL wird von einem WFP-basierten Umleitungsdienst verwendet, um den Umleitungskontext für einen Umleitungsdatensatz von der akzeptierten TCP/IP-Paketverbindung (z. B. dem verbundenen Socket für einen TCP-Socket oder einem UDP-Socket) abzurufen, der von der begleitgeschützten Legende, die auf ALE_CONNECT_REDIRECT Ebenen registriert ist, an diesen umgeleitet wird. Der Umleitungskontext ist ein optionaler vom Treiber zugewiesener Kontext, der verwendet wird, wenn der aktuelle Umleitungsstatus einer Verbindung darin besteht, dass die Verbindung vom aufrufenden Umleitungsdienst umgeleitet wurde oder die Verbindung zuvor vom aufrufenden Umleitungsdienst umgeleitet wurde, später aber erneut von einem anderen Umleitungsdienst umgeleitet wurde. Bei einer TCP-Proxyverbindung überträgt der Umleitungsdienst den abgerufenen Umleitungsdatensatz an den TCP-Socket, den er verwendet, um den ursprünglichen Inhalt mithilfe der SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL zu proxyn.
Wenn der Umleitungsdienst z. B. einen Nicht-TCP-Socket (UDP) umleitet, geben die vom SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL zurückgegebenen Umleitungsdatensätze dies an den Umleitungsdienst mithilfe der WSAMSG-Struktur an, die mit der funktion LPFN_WSARECVMSG (WSARecvMsg) verwendet wird. Das Control-Element der WSAMSG-Struktur verfügt über eine cmsg_type in der WSACMSGHDR-Struktur , die auf IP_CONNECTION_REDIRECT_RECORD festgelegt ist. Der Parameter LPFN_WSARECVMSG (WSARecvMsg) muss vom Umleitungsdienst bereitgestellt werden, wenn Nicht-TCP-Umleitungen akzeptiert werden.
Bei Nicht-TCP-Datenverkehr wird der Umleitungsdatensatz mithilfe der WSAMSG-Struktur mit der WSASendMsg-Funktion weitergeleitet.
Beachten Sie, dass für Nicht-TCP-Datenverkehr nur das Datenflusserstellungspaket die IP_CONNECTION_REDIRECT_RECORD enthält. Daher muss nur das erste Proxiepaket diese Informationen mithilfe der funktion LPFN_WSARECVMSG (WSARecvMsg) enthalten.
Da der WFP-Umleitungsdatensatz ein Datenblob mit variabler Länge ist, kann der Aufrufer entweder einen großen Ausgabepuffer bereitstellen (z. B. ein 1.024 Bytepuffer, auf den der lpvOutBuffer-Parameter verweist), oder eine Ausgabepuffergröße im cbOutBuffer-Parameter von 0 übergeben, um die Puffergröße abzufragen, die für das zurückgegebene Blob erforderlich ist. Wenn die Größe des Ausgabepuffers nicht ausreicht, um die Daten zu enthalten, geben die Funktionen WSAIoctl oder WSPIoctlERROR_INSUFFICIENT_BUFFER zurück, und die erforderliche Puffergröße wird im Wert zurückgegeben, auf den der parameter lpcbBytesReturned verweist.
Die Anwendung, die den SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT aufruft, muss das Blob, das den abgerufenen Umleitungskontext enthält, nicht verstehen. Dies ist ein undurchsichtiges Datenblob, das die Anwendung abrufen und an den neuen Socket zurückgeben muss.