código de control de SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS

Artículo
06/12/2023

Descripción

El código de control SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS recupera el registro de redireccionamiento de la conexión TCP/IP aceptada para que la use un servicio de redirección de la Plataforma de filtrado de Windows (PMA).

Para realizar esta operación, llame a la función WSAIoctl o WSPIoctl con los parámetros siguientes.

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
);

Parámetros

s

Descriptor que identifica un socket.

dwIoControlCode

Código de control de la operación. Use SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS para esta operación.

lpvInBuffer

Puntero al búfer de entrada. Este parámetro no se usa para esta operación.

cbInBuffer

Tamaño, en bytes, del búfer de entrada. Este parámetro no se usa para esta operación.

lpvOutBuffer

Puntero al búfer de salida. Este parámetro debe apuntar a un tipo de datos ULONG si los parámetros lpOverlapped y lpCompletionRoutine son NULL.

cbOutBuffer

Tamaño, en bytes, del búfer de salida. Este parámetro debe ser al menos el tamaño de un tipo de datos ULONG .

lpcbBytesReturned

Puntero a una variable que recibe el tamaño, en bytes, de los datos almacenados en el búfer de salida.

Si el búfer de salida es demasiado pequeño, se produce un error en la llamada, WSAGetLastError devuelve WSAEINVAL y el parámetro lpcbBytesReturned apunta a un valor DWORD de cero.

Si lpOverlapped es NULL, el valor DWORD al que apunta el parámetro lpcbBytesReturned devuelto en una llamada correcta no puede ser cero.

Si el parámetro lpOverlapped no es NULL para sockets superpuestos, las operaciones que no se pueden completar inmediatamente se iniciarán y la finalización se indicará en un momento posterior. El valor DWORD al que apunta el parámetro lpcbBytesReturned que se devuelve puede ser cero, ya que el tamaño de los datos almacenados no se puede determinar hasta que se haya completado la operación superpuesta. El estado de finalización final se puede recuperar cuando se señala el método de finalización adecuado cuando se ha completado la operación.

lpvOverlapped

Puntero a una estructura WSAOVERLAPPED .

Si el socket s se creó sin el atributo superpuesto, se omite el parámetro lpOverlapped .

Si se abrió s con el atributo superpuesto y el parámetro lpOverlapped no es NULL, la operación se realiza como una operación superpuesta (asincrónica). En este caso, el parámetro lpOverlapped debe apuntar a una estructura WSAOVERLAPPED válida.

Para las operaciones superpuestas, la función WSAIoctl o WSPIoctl devuelve inmediatamente y el método de finalización adecuado se señala cuando se ha completado la operación. De lo contrario, la función no devuelve hasta que se haya completado la operación o se produzca un error.

lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Puntero a la rutina de finalización a la que se llama cuando se ha completado la operación (se omite para sockets no superpuestos).

lpThreadId

Puntero a una estructura WSATHREADID que usará el proveedor en una llamada posterior a WPUQueueApc. El proveedor debe almacenar la estructura WSATHREADID a la que se hace referencia (no el puntero a la misma) hasta después de que la función WPUQueueApc devuelva.

Nota Este parámetro solo se aplica a la función WSPIoctl .

lpErrno

Puntero al código de error.

Nota Este parámetro solo se aplica a la función WSPIoctl .

Valor devuelto

Si la operación se completa correctamente, la función WSAIoctl o WSPIoctl devuelve cero.

Si se produce un error en la operación o está pendiente, la función WSAIoctl o WSPIoctl devuelve SOCKET_ERROR. Para obtener información de error extendida, llame a WSAGetLastError.

Código de error	Significado
ERROR_INSUFFICIENT_BUFFER	El área de datos que se pasa a una llamada del sistema es demasiado pequeña. Este error se devuelve si el búfer apuntado por el parámetro lpvOutBuffer con un tamaño de búfer pasado en el parámetro cbOutBuffer es demasiado pequeño. El tamaño del búfer necesario se devolverá en el parámetro lpcbBytesReturned .
WSA_IO_PENDING	Una operación superpuesta se inició correctamente y la finalización se indicará en un momento posterior.
WSA_OPERATION_ABORTED	Se canceló una operación superpuesta debido al cierre del socket o a la ejecución del comando SIO_FLUSH IOCTL.
WSAEFAULT	El parámetro lpvOutBuffer, lpcbBytesReturned, lpOverlapped o lpCompletionRoutine no está totalmente incluido en una parte válida del espacio de direcciones del usuario.
WSAEINPROGRESS	La función se invoca cuando una devolución de llamada está en curso.
WSAEINTR	Se interrumpió una operación de bloqueo.
WSAEINVAL	El parámetro dwIoControlCode no es un comando válido o un parámetro de entrada especificado no es aceptable o el comando no es aplicable al tipo de socket especificado. Este error se devuelve si el parámetro cbOutBuffer es menor que el tamaño de un tipo de datos ULONG .
WSAENETDOWN	Error en el subsistema de red.
WSAENOPROTOOPT	La opción socket no se admite en el protocolo especificado.
WSAENOTCONN	El socket s no está conectado.
WSAENOTSOCK	El descriptor s no es un socket.
WSAEOPNOTSUPP	No se admite el comando IOCTL especificado. Este error se devuelve si el proveedor de transporte no admite el SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL.

Comentarios

El SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL se admite en Windows 8 y Windows Server 2012 y versiones posteriores del sistema operativo.

EL PMA permite el acceso a la ruta de procesamiento de paquetes TCP/IP, donde los paquetes salientes y entrantes se pueden examinar o cambiar antes de permitirles procesarlos más. Al pulsar en la ruta de procesamiento tcp/IP, los proveedores de software independientes (ISV) pueden crear más fácilmente firewalls, software antivirus, software de diagnóstico y otros tipos de aplicaciones y servicios. EL PMA proporciona componentes en modo de usuario y modo kernel para que los ISV de terceros puedan participar en las decisiones de filtrado que tienen lugar en varias capas de la pila de protocolos TCP/IP y en todo el sistema operativo. La característica de redirección de conexión DE PMA permite que un controlador de kernel de llamada DE PMA redirija una conexión localmente a un proceso en modo de usuario, realice la inspección de contenido en modo de usuario y reenvíe el contenido inspeccionado mediante una conexión diferente al destino original.

El SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL y otros IOCTLS relacionados son componentes en modo de usuario que se usan para permitir que varias aplicaciones proxy de conexión basadas en PMA inspeccionen el mismo flujo de tráfico de manera cooperativa. Cada agente de inspección puede volver a inspeccionar de forma segura el tráfico de red que ya ha sido inspeccionado por otro agente de inspección. Con la presencia de varios servidores proxy (desarrollados por diferentes ISV, por ejemplo), la conexión usada por un proxy para comunicarse con el destino final podría redirigirse a su vez por un segundo proxy y esa nueva conexión podría ser redirigida de nuevo por el proxy original. Sin el seguimiento de conexiones, es posible que la conexión original nunca llegue a su destino final, ya que se bloquea en un bucle proxy infinito.

El SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL se usa para proporcionar el seguimiento de conexiones proxy en las conexiones de socket redirigidas. Esta característica del PMA facilita el seguimiento de los registros de redireccionamiento desde el redireccionamiento inicial de una conexión a la conexión final al destino.

El SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL lo usa un servicio de redireccionamiento basado en PMA para recuperar el registro de redireccionamiento de la conexión de paquetes TCP/IP aceptada (el socket conectado para un socket TCP o un socket UDP, por ejemplo) redirigido a él por su llamada en modo kernel complementario registrada en ALE_CONNECT_REDIRECT capas en un controlador en modo kernel. El SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL es utilizado por un servicio de redireccionamiento basado en EL PMA para recuperar el contexto de redireccionamiento de un registro de redireccionamiento de la conexión de paquete TCP/IP aceptada (el socket conectado para un socket TCP o un socket UDP, por ejemplo) redirigido a él por su llamada complementaria registrada en capas de ALE_CONNECT_REDIRECT . El contexto de redireccionamiento es un contexto opcional asignado por el controlador que se usa si el estado de redirección actual de una conexión es que el servicio de redirección de llamada redireccionó la conexión o que el servicio de redireccionamiento de llamada redirigió anteriormente, pero más tarde lo redirigió de nuevo un servicio de redireccionamiento diferente. Para una conexión de proxy TCP, el servicio de redirección transfiere el registro de redireccionamiento recuperado al socket TCP que usa para proxy del contenido original mediante el SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL.

Cuando el servicio de redirección redirige un socket no TCP (UDP, por ejemplo), los registros de redireccionamiento devueltos por el SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL indican esto al servicio de redireccionamiento mediante la estructura WSAMSG usada con la función LPFN_WSARECVMSG (WSARecvMsg). El miembro Control de la estructura WSAMSG tendría un cmsg_type en la estructura WSACMSGHDR establecida en IP_CONNECTION_REDIRECT_RECORD. El servicio de redireccionamiento debe proporcionar el parámetro LPFN_WSARECVMSG (WSARecvMsg) al aceptar redireccionamientos que no son TCP.

Para el tráfico que no es TCP, el registro de redireccionamiento se reenvía mediante la estructura WSAMSG con la función WSASendMsg .

Tenga en cuenta que para el tráfico que no es TCP, solo el paquete de creación de flujo llevará el IP_CONNECTION_REDIRECT_RECORD. Como resultado, solo el primer paquete proxy debe incluir esta información mediante la función LPFN_WSARECVMSG (WSARecvMsg).

Dado que el registro de redirección del PMA es un blob de datos de longitud variable, el autor de la llamada puede proporcionar un búfer de salida grande (un búfer de 1024 bytes al que apunta el parámetro lpvOutBuffer , por ejemplo) o puede pasar un tamaño de búfer de salida en el parámetro cbOutBuffer de 0 para consultar el tamaño del búfer necesario para contener el blob devuelto. Si el tamaño del búfer de salida no es suficiente para contener los datos, las funciones WSAIoctl o WSPIoctl devolverán ERROR_INSUFFICIENT_BUFFER y el tamaño de búfer necesario se devolverá en el valor al que apunta el parámetro lpcbBytesReturned .

La aplicación que llama al SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT no necesita comprender el blob que contiene el contexto de redireccionamiento recuperado. Se trata de un blob opaco de datos que la aplicación necesita para recuperar y volver al nuevo socket.