SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS-Steuerungscode

Artikel
06/12/2023

Beschreibung

Der SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS-Steuerelementcode legt den Umleitungsdatensatz auf den neuen TCP-Socket fest, der für die Verbindung mit dem endgültigen Ziel verwendet wird, um von einem WFP-Umleitungsdienst (Windows Filtering Platform) verwendet zu werden.

Rufen Sie zum Ausführen dieses Vorgangs die Funktion WSAIoctl oder WSPIoctl mit den folgenden Parametern auf.

int WSAIoctl(
  (socket) s,                              // descriptor identifying a socket
  SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS, // dwIoControlCode
  (LPVOID) lpvInputBuffer,                 // lpvInBuffer
  (DWORD) cbInputBuffer,                   // cbInBuffer
  NULL,                                    // output buffer
  0,                                       // size of output buffer
  (LPDWORD) lpcbBytesReturned,             // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,          // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine, // completion routine
);

int WSPIoctl(
  (socket) s,                              // descriptor identifying a socket
  SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS, // dwIoControlCode
  (LPVOID) lpvInputBuffer,                 // lpvInBuffer
  (DWORD) cbInputBuffer,                   // cbInBuffer
  NULL,                                    // output buffer
  0,                                       // size of output buffer
  (LPDWORD) lpcbBytesReturned,             // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,          // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,              // a WSATHREADID structure
  (LPINT) lpErrno                          // a pointer to the error code.
);

Parameter

s

Ein Deskriptor, der einen Socket identifiziert.

dwIoControlCode

Der Steuerelementcode für den Vorgang. Verwenden Sie für diesen Vorgang SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS .

lpvInBuffer

Ein Zeiger auf den Eingabepuffer. Dieser Parameter enthält einen Zeiger auf den WFP-Umleitungsdatensatz, der dem Socket zugeordnet ist.

cbInBuffer

Die Größe des Eingabepuffers in Bytes.

lpvOutBuffer

Ein Zeiger auf den Ausgabepuffer. Dieser Parameter wird für diesen Vorgang nicht verwendet.

cbOutBuffer

Die Größe des Ausgabepuffers in Bytes. Dieser Parameter muss auf 0 festgelegt werden.

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 lpcbBytesReturned-Parameter verweist auf einen DWORD-Wert von 0.

Wenn lpOverlappedNULL ist, kann der DWORD-Wert , auf den der parameter lpcbBytesReturned verweist, der bei einem erfolgreichen Aufruf zurückgegeben wird, nicht 0 sein.

Wenn der lpOverlapped-Parameter für überlappende Sockets nicht NULL ist, werden Vorgänge initiiert, die nicht sofort abgeschlossen werden können, und die Vervollständigung wird zu einem späteren Zeitpunkt angezeigt. Der vom zurückgegebenen parameter lpcbBytesReturned angegebene DWORD-Wert kann 0 sein, da die Größe der gespeicherten Daten erst bestimmt werden kann, wenn der überlappende Vorgang abgeschlossen ist. Die endgültige Vervollständigung 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 Vervollständigungsmethode 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 Vervollständigungsroutine, 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 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 wurde, 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
WSA_IO_PENDING	Der überlappende E/A-Vorgang wird ausgeführt. Dieser Wert wird zurückgegeben, wenn ein überlappender Vorgang erfolgreich initiiert wurde und der Abschluss zu einem späteren Zeitpunkt angezeigt wird.
WSA_OPERATION_ABORTED	Der E/A-Vorgang wurde wegen eines Threadendes oder einer Anwendungsanforderung abgebrochen. Dieser Fehler wird zurückgegeben, wenn ein überlappender Vorgang aufgrund des Schließens des Sockets oder der Ausführung des SIO_FLUSH IOCTL-Befehls abgebrochen wurde.
WSAEACCES	Es wurde versucht, auf einen Socket auf eine Weise zuzugreifen, die durch seine Zugriffsberechtigungen verboten ist. Dieser Fehler wird unter folgenden Bedingungen zurückgegeben: Dem Benutzer fehlen die erforderlichen Administratorrechte auf dem lokalen Computer, oder die Anwendung wird nicht in einer erweiterten Shell als integrierter Administrator (`RunAs administrator`) ausgeführt.
WSAEFAULT	Das System hat beim Versuch, ein Zeigerargument in einem Aufruf zu verwenden, eine ungültige Zeigeradresse erkannt. Dieser Fehler wird zurückgegeben, wenn der Parameter lpvInBuffer, lpvoutBuffer, lpcbBytesReturned, lpOverlapped oder lpCompletionRoutine nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten ist.
WSAEINPROGRESS	Ein Blockierungsvorgang wird momentan ausgeführt. Dieser Fehler wird zurückgegeben, wenn die Funktion aufgerufen wird, wenn ein Rückruf ausgeführt wird.
WSAEINTR	Ein blockierender Vorgang wurde durch einen Aufruf von WSACancelBlockingCall unterbrochen. Dieser Fehler wird zurückgegeben, wenn ein blockierende Vorgang unterbrochen wurde.
WSAEINVAL	Ein ungültiges Argument wurde angegeben. Dieser Fehler wird zurückgegeben, wenn der dwIoControlCode-Parameter kein gültiger Befehl ist, ein angegebener Eingabeparameter nicht akzeptabel ist oder der Befehl nicht auf den angegebenen Sockettyp anwendbar ist.
WSAENETDOWN	Bei einem Socketvorgang war das Netzwerk inaktiv. Dieser Fehler wird zurückgegeben, wenn für das Netzwerksubsystem ein Fehler aufgetreten ist.
WSAENOTSOCK	Es wurde ein Vorgang für etwas versucht, das kein Socket ist. Dieser Fehler wird zurückgegeben, wenn der Deskriptor s kein Socket ist.
WSAEOPNOTSUPP	Der versuchte Vorgang wird für den Typ des Objekts, auf das verwiesen wird, nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der angegebene IOCTL-Befehl nicht unterstützt wird. Dieser Fehler wird auch zurückgegeben, wenn die SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL vom Transportanbieter nicht unterstützt wird.

Bemerkungen

Die SIO_SET_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 Das Erschließen des TCP/IP-Verarbeitungspfads können unabhängige Softwareanbieter (INDEPENDENT Software Vendors, ISVs) leichter Firewalls, Antivirensoftware, Diagnosesoftware und andere Arten von Anwendungen und Diensten erstellen. WFP stellt Benutzermodus- und Kernelmoduskomponenten bereit, sodass IsVs von Drittanbietern an den Filterentscheidungen teilnehmen können, die auf mehreren Ebenen im TCP/IP-Protokollstapel und im gesamten Betriebssystem stattfinden. Die WFP-Verbindungsumleitung ermöglicht es einem WFP-Callout-Kerneltreiber, eine Verbindung lokal an einen Benutzermodusprozess umzuleiten, Inhaltsüberprüfungen im Benutzermodus durchzuführen und den überprüften Inhalt mit einer anderen Verbindung an das ursprüngliche Ziel weiterzuleiten.

Die SIO_SET_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 kooperativ zu überprüfen. 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 endgültigen Ziel verwendet wird, wiederum von einem zweiten Proxy umgeleitet werden, und diese neue Verbindung könnte erneut vom ursprünglichen Proxy umgeleitet werden. Ohne Die Verbindungsnachverfolgung erreicht die ursprüngliche Verbindung möglicherweise nie ihr endgültiges Ziel, da sie in einer endlosen Proxyschleife hängen bleibt.

Die SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL wird verwendet, um die Verbindungsnachverfolgung 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 zum Ziel.

Die SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL wird von einem WFP-basierten Umleitungsdienst verwendet, um den Umleitungsdatensatz aus der akzeptierten TCP/IP-Paketverbindung abzurufen (z. B. der verbundene Socket für einen TCP-Socket oder einen UDP-Socket), der von seiner begleitbasierten 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 ruft den Umleitungskontext für einen Umleitungsdatensatz ab, der verwendet wird. Der Umleitungskontext ist optional und wird verwendet, 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 wieder von einem anderen Umleitungsdienst umgeleitet wurde. Der Umleitungsdienst überträgt den abgerufenen Umleitungsdatensatz an den TCP-Socket, den er verwendet, um den ursprünglichen Inhalt mithilfe des SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL zu proxyn.

Die Anwendung, die den SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL aufruft, muss das Blob mit dem festzulegenden Umleitungsdatensatz nicht verstehen. Dies ist ein undurchsichtiges Datenblob, das die Anwendung an den neuen Socket zurückgeben muss.