Código de controle SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS

Artigo
06/12/2023

Descrição

O código de controle SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS define o registro de redirecionamento para o novo soquete TCP usado para se conectar ao destino final para uso por um serviço de redirecionamento da Plataforma de Filtragem do Windows (WFP).

Para executar essa operação, chame a função WSAIoctl ou WSPIoctl com os parâmetros a seguir.

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

Parâmetros

s

Um descritor que identifica um soquete.

Dwiocontrolcode

O código de controle para a operação. Use SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS para esta operação.

Lpvinbuffer

Um ponteiro para o buffer de entrada. Esse parâmetro contém um ponteiro para o registro de redirecionamento WFP associado ao soquete.

Cbinbuffer

O tamanho, em bytes, do buffer de entrada.

Lpvoutbuffer

Um ponteiro para o buffer de saída. Esse parâmetro não é usado para essa operação.

cbOutBuffer

O tamanho, em bytes, do buffer de saída. Esse parâmetro deve ser definido como zero.

Lpcbbytesreturned

Um ponteiro para uma variável que recebe o tamanho, em bytes, dos dados armazenados no buffer de saída.

Se o buffer de saída for muito pequeno, a chamada falhará, WSAGetLastError retornará WSAEINVAL e o parâmetro lpcbBytesReturned apontará para um valor DWORD igual a zero.

Se lpOverlapped for NULL, o valor DWORD apontado pelo parâmetro lpcbBytesReturned retornado em uma chamada bem-sucedida não poderá ser zero.

Se o parâmetro lpOverlapped não for NULL para soquetes sobrepostos, as operações que não podem ser concluídas imediatamente serão iniciadas e a conclusão será indicada posteriormente. O valor DWORD apontado pelo parâmetro lpcbBytesReturned retornado pode ser zero, pois o tamanho dos dados armazenados não pode ser determinado até que a operação sobreposta seja concluída. O status de conclusão final pode ser recuperado quando o método de conclusão apropriado é sinalizado quando a operação é concluída.

lpvOverlapped

Um ponteiro para uma estrutura WSAOVERLAPPED .

Se soquete s tiver sido criado sem o atributo sobreposto, o parâmetro lpOverlapped será ignorado.

Se s tiver sido aberto com o atributo sobreposto e o parâmetro lpOverlapped não for NULL, a operação será executada como uma operação sobreposta (assíncrona). Nesse caso, o parâmetro lpOverlapped deve apontar para uma estrutura WSAOVERLAPPED válida.

Para operações sobrepostas, a função WSAIoctl ou WSPIoctl retorna imediatamente e o método de conclusão apropriado é sinalizado quando a operação é concluída. Caso contrário, a função não retornará até que a operação seja concluída ou ocorra um erro.

Lpcompletionroutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Um ponteiro para a rotina de conclusão chamado quando a operação foi concluída (ignorado para soquetes não sobrepostos).

lpThreadId

Um ponteiro para uma estrutura WSATHREADID a ser usada pelo provedor em uma chamada subsequente para WPUQueueApc. O provedor deve armazenar a estrutura WSATHREADID referenciada (não o ponteiro para o mesmo) até que a função WPUQueueApc retorne.

Nota Esse parâmetro se aplica somente à função WSPIoctl .

Lperrno

Um ponteiro para o código de erro.

Nota Esse parâmetro se aplica somente à função WSPIoctl .

Valor retornado

Se a operação for concluída com êxito, a função WSAIoctl ou WSPIoctl retornará zero.

Se a operação falhar ou estiver pendente, a função WSAIoctl ou WSPIoctl retornará SOCKET_ERROR. Para obter informações de erro estendidas, chame WSAGetLastError.

Código do erro	Significado
WSA_IO_PENDING	A operação de E/S sobreposta está em andamento. Esse valor será retornado se uma operação sobreposta tiver sido iniciada com êxito e a conclusão será indicada posteriormente.
WSA_OPERATION_ABORTED	A operação de E/S foi anulada devido ao encerramento de um thread ou a uma solicitação de aplicativo. Esse erro será retornado se uma operação sobreposta tiver sido cancelada devido ao fechamento do soquete ou à execução do comando IOCTL SIO_FLUSH .
WSAEACCES	Foi feita uma tentativa de acessar um soquete de forma proibida por suas permissões de acesso. Esse erro é retornado sob várias condições que incluem o seguinte: o usuário não tem os privilégios administrativos necessários no computador local ou o aplicativo não está em execução em um shell aprimorado como administrador interno (`RunAs administrator`).
WSAEFAULT	O sistema detectou um endereço de ponteiro inválido ao tentar usar um argumento de ponteiro em uma chamada. Esse erro é retornado do parâmetro lpvInBuffer, lpvoutBuffer, lpcbBytesReturned, lpOverlapped ou lpCompletionRoutine não está totalmente contido em uma parte válida do espaço de endereço do usuário.
WSAEINPROGRESS	Uma operação de bloqueio está atualmente em execução. Esse erro será retornado se a função for invocada quando um retorno de chamada estiver em andamento.
WSAEINTR	Uma operação de bloqueio foi interrompida por uma chamada para WSACancelBlockingCall. Esse erro será retornado se uma operação de bloqueio tiver sido interrompida.
WSAEINVAL	Foi fornecido um argumento inválido. Esse erro será retornado se o parâmetro dwIoControlCode não for um comando válido ou se um parâmetro de entrada especificado não for aceitável ou o comando não for aplicável ao tipo de soquete especificado.
WSAENETDOWN	Uma operação de soquete encontrou uma rede inoperante. Esse erro será retornado se o subsistema de rede falhar.
WSAENOTSOCK	Uma operação foi tentada em algo que não é um soquete. Esse erro será retornado se o descritor s não for um soquete.
WSAEOPNOTSUPP	Não há suporte para a tentativa de operação para o tipo de objeto referenciado. Esse erro será retornado se não houver suporte para o comando IOCTL especificado. Esse erro também será retornado se o SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL não tiver suporte do provedor de transporte.

Comentários

O SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL tem suporte em Windows 8 e Windows Server 2012 e versões posteriores do sistema operacional.

O WFP permite acesso ao caminho de processamento de pacotes TCP/IP, no qual os pacotes de saída e de entrada podem ser examinados ou alterados antes de permitir que eles sejam processados ainda mais. Ao tocar no caminho de processamento TCP/IP, os ISVs (fornecedores independentes de software) podem criar firewalls, software antivírus, software de diagnóstico e outros tipos de aplicativos e serviços com mais facilidade. O WFP fornece componentes do modo de usuário e do modo kernel para que ISVs de terceiros possam participar das decisões de filtragem que ocorrem em várias camadas na pilha de protocolos TCP/IP e em todo o sistema operacional. O recurso de redirecionamento de conexão WFP permite que um driver de kernel de texto explicativo WFP redirecione uma conexão localmente para um processo de modo de usuário, execute a inspeção de conteúdo no modo de usuário e encaminhe o conteúdo inspecionado usando uma conexão diferente com o destino original.

O SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL e vários outros IOCTLS relacionados são componentes do modo de usuário usados para permitir que vários aplicativos proxy de conexão baseados em WFP inspecionem o mesmo fluxo de tráfego de maneira cooperativa. Cada agente de inspeção pode inspecionar novamente com segurança o tráfego de rede que já foi inspecionado por outro agente de inspeção. Com a presença de vários proxies (desenvolvidos por ISVs diferentes, por exemplo), a conexão usada por um proxy para se comunicar com o destino final poderia, por sua vez, ser redirecionada por um segundo proxy e essa nova conexão poderia ser redirecionada novamente pelo proxy original. Sem o rastreamento de conexão, a conexão original pode nunca chegar ao destino final, pois ela fica presa em um loop de proxy infinito.

O SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL é usado para fornecer controle de conexão com proxie em conexões de soquete redirecionadas. Esse recurso WFP facilita o acompanhamento de registros de redirecionamento do redirecionamento inicial de uma conexão com a conexão final com o destino.

O SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL é usado por um serviço de redirecionamento baseado em WFP para recuperar o registro de redirecionamento da conexão de pacote TCP/IP aceita (o soquete conectado para um soquete TCP ou um soquete UDP, por exemplo) redirecionado a ele por seu texto explicativo complementar no modo kernel registrado em camadas de ALE_CONNECT_REDIRECT em um driver no modo kernel. O SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL recupera o contexto de redirecionamento para um registro de redirecionamento, que é usado. O contexto de redirecionamento é opcional e é usado se o estado de redirecionamento atual de uma conexão é que a conexão foi redirecionada pelo serviço de redirecionamento de chamada ou a conexão foi redirecionada anteriormente pelo serviço de redirecionamento de chamada, mas posteriormente redirecionada novamente por um serviço de redirecionamento diferente. O serviço de redirecionamento transfere o registro de redirecionamento recuperado para o soquete TCP que ele usa para fazer proxy do conteúdo original usando o SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL.

O aplicativo que chama o SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL não precisa entender o blob que contém o registro de redirecionamento que está sendo definido. Esse é um blob opaco de dados que o aplicativo precisa passar de volta para o novo soquete.