SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS, code de contrôle

Article
06/12/2023

Description

Le code de contrôle SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS définit l’enregistrement de redirection sur le nouveau socket TCP utilisé pour la connexion à la destination finale à utiliser par un service de redirection de la plateforme de filtrage Windows (PAM).

Pour effectuer cette opération, appelez la fonction WSAIoctl ou WSPIoctl avec les paramètres suivants.

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

Paramètres

s

Descripteur identifiant un socket.

dwIoControlCode

Code de contrôle pour l’opération. Utilisez SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS pour cette opération.

lpvInBuffer

Pointeur vers la mémoire tampon d’entrée. Ce paramètre contient un pointeur vers l’enregistrement de redirection PAM associé au socket.

cbInBuffer

Taille, en octets, de la mémoire tampon d’entrée.

lpvOutBuffer

Pointeur vers la mémoire tampon de sortie. Ce paramètre n’est pas utilisé pour cette opération.

cbOutBuffer

Taille, en octets, de la mémoire tampon de sortie. Ce paramètre doit être défini sur zéro.

lpcbBytesReturned

Pointeur vers une variable qui reçoit la taille, en octets, des données stockées dans la mémoire tampon de sortie.

Si la mémoire tampon de sortie est trop petite, l’appel échoue, WSAGetLastError renvoie WSAEINVAL et le paramètre lpcbBytesReturned pointe vers une valeur DWORD de zéro.

Si lpOverlapped a la valeur NULL, la valeur DWORD pointée par le paramètre lpcbBytesReturned retourné lors d’un appel réussi ne peut pas être égale à zéro.

Si le paramètre lpOverlapped n’est pas NULL pour les sockets superposés, les opérations qui ne peuvent pas être effectuées immédiatement sont lancées et l’achèvement sera indiqué ultérieurement. La valeur DWORD pointée par le paramètre lpcbBytesReturned retourné peut être égale à zéro, car la taille des données stockées ne peut pas être déterminée tant que l’opération superposée n’est pas terminée. La status d’achèvement finale peut être récupérée lorsque la méthode d’achèvement appropriée est signalée lorsque l’opération est terminée.

lpvOverlapped

Pointeur vers une structure WSAOVERLAPPED .

Si le socket s a été créé sans l’attribut superposé, le paramètre lpOverlapped est ignoré.

Si s a été ouvert avec l’attribut qui se chevauche et que le paramètre lpOverlapped n’a pas la valeur NULL, l’opération est effectuée en tant qu’opération (asynchrone) qui se chevauche. Dans ce cas, le paramètre lpOverlapped doit pointer vers une structure WSAOVERLAPPED valide.

Pour les opérations qui se chevauchent, la fonction WSAIoctl ou WSPIoctl retourne immédiatement, et la méthode d’achèvement appropriée est signalée une fois l’opération terminée. Sinon, la fonction ne retourne pas tant que l’opération n’est pas terminée ou qu’une erreur se produit.

lpCompletionRoutine

Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Pointeur vers la routine d’achèvement appelée une fois l’opération terminée (ignorée pour les sockets qui ne se chevauchent pas).

lpThreadId

Pointeur vers une structure WSATHREADID à utiliser par le fournisseur dans un appel ultérieur à WPUQueueApc. Le fournisseur doit stocker la structure WSATHREADID référencée (pas le pointeur vers le même) jusqu’à ce que la fonction WPUQueueApc soit retournée.

Note Ce paramètre s’applique uniquement à la fonction WSPIoctl .

lpErrno

Pointeur vers le code d’erreur.

Note Ce paramètre s’applique uniquement à la fonction WSPIoctl .

Valeur retournée

Si l’opération se termine correctement, la fonction WSAIoctl ou WSPIoctl retourne zéro.

Si l’opération échoue ou est en attente, la fonction WSAIoctl ou WSPIoctl retourne SOCKET_ERROR. Pour obtenir des informations d’erreur étendues, appelez WSAGetLastError.

Code d'erreur	Signification
WSA_IO_PENDING	L’opération d’E/S qui se chevauche est en cours. Cette valeur est retournée si une opération qui se chevauche a été lancée avec succès et que l’achèvement sera indiqué ultérieurement.
WSA_OPERATION_ABORTED	L'opération d'E/S a été abandonnée en raison de l'arrêt d'un thread ou de la requête d'une application. Cette erreur est retournée si une opération qui se chevauche a été annulée en raison de la fermeture du socket ou de l’exécution de la commande IOCTL SIO_FLUSH .
WSAEACCES	Une tentative d’accès à un socket a été effectuée d’une manière interdite par ses autorisations d’accès. Cette erreur est retournée dans plusieurs conditions, notamment : l’utilisateur n’a pas les privilèges d’administration requis sur l’ordinateur local ou l’application ne s’exécute pas dans un interpréteur de commandes amélioré en tant qu’administrateur intégré (`RunAs administrator`).
WSAEFAULT	Le système a détecté une adresse de pointeur non valide lors de la tentative d’utilisation d’un argument pointeur dans un appel. Cette erreur est retournée du paramètre lpvInBuffer, lpvoutBuffer, lpcbBytesReturned, lpOverlapped ou lpCompletionRoutine n’est pas totalement contenu dans une partie valide de l’espace d’adressage utilisateur.
WSAEINPROGRESS	Une opération de blocage est actuellement en cours d'exécution. Cette erreur est retournée si la fonction est appelée lorsqu’un rappel est en cours.
WSAEINTR	Une opération de blocage a été interrompue par un appel à WSACancelBlockingCall. Cette erreur est retournée si une opération de blocage a été interrompue.
WSAEINVAL	Argument non valide fourni. Cette erreur est retournée si le paramètre dwIoControlCode n’est pas une commande valide, si un paramètre d’entrée spécifié n’est pas acceptable ou si la commande n’est pas applicable au type de socket spécifié.
WSAENETDOWN	Une opération de socket a rencontré un réseau inactif. Cette erreur est retournée si le sous-système réseau a échoué.
WSAENOTSOCK	Une opération a été tentée sur un objet qui n’est pas un socket. Cette erreur est retournée si le descripteur s n’est pas un socket.
WSAEOPNOTSUPP	L’opération tentée n’est pas prise en charge pour le type d’objet référencé. Cette erreur est retournée si la commande IOCTL spécifiée n’est pas prise en charge. Cette erreur est également retournée si le SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL n’est pas pris en charge par le fournisseur de transport.

Notes

Le SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL est pris en charge sur Windows 8, Windows Server 2012 et versions ultérieures du système d’exploitation.

PAM autorise l’accès au chemin de traitement des paquets TCP/IP, dans lequel les paquets sortants et entrants peuvent être examinés ou modifiés avant de leur permettre d’être traités plus en détail. En tirant parti du chemin de traitement TCP/IP, les éditeurs de logiciels indépendants peuvent plus facilement créer des pare-feu, des logiciels antivirus, des logiciels de diagnostic et d’autres types d’applications et de services. PAM fournit des composants en mode utilisateur et en mode noyau afin que les éditeurs de logiciels indépendants tiers puissent participer aux décisions de filtrage qui se produisent sur plusieurs couches de la pile de protocoles TCP/IP et dans tout le système d’exploitation. La fonctionnalité de redirection de connexion PAM permet à un pilote de noyau de légende PAM de rediriger une connexion localement vers un processus en mode utilisateur, d’effectuer une inspection du contenu en mode utilisateur et de transférer le contenu inspecté à l’aide d’une connexion différente à la destination d’origine.

Les SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL et plusieurs autres IOCTLS connexes sont des composants en mode utilisateur utilisés pour permettre à plusieurs applications de proxy de connexion basées sur LE PAM d’inspecter le même flux de trafic de manière coopérative. Chaque agent d’inspection peut inspecter à nouveau en toute sécurité le trafic réseau qui a déjà été inspecté par un autre agent d’inspection. Avec la présence de plusieurs proxys (développés par différents éditeurs de logiciels indépendants, par exemple), la connexion utilisée par un proxy pour communiquer avec la destination finale peut à son tour être redirigée par un deuxième proxy, et cette nouvelle connexion peut à nouveau être redirigée par le proxy d’origine. Sans suivi des connexions, la connexion d’origine risque de ne jamais atteindre sa destination finale, car elle est bloquée dans une boucle de proxy infinie.

Le SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL est utilisé pour fournir un suivi des connexions proxiées sur les connexions de socket redirigées. Cette fonctionnalité PAM facilite le suivi des enregistrements de redirection à partir de la redirection initiale d’une connexion vers la connexion finale vers la destination.

Le SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS IOCTL est utilisé par un service de redirection basé sur PAM pour récupérer l’enregistrement de redirection à partir de la connexion de paquet TCP/IP acceptée (le socket connecté pour un socket TCP ou un socket UDP, par exemple) redirigé vers celui-ci par sa légende en mode noyau complémentaire inscrite à ALE_CONNECT_REDIRECT couches dans un pilote en mode noyau. Le SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT IOCTL récupère le contexte de redirection d’un enregistrement de redirection, qui est utilisé. Le contexte de redirection est facultatif et est utilisé si l’état de redirection actuel d’une connexion est que la connexion a été redirigée par le service de redirection appelant ou que la connexion a été précédemment redirigée par le service de redirection appelant, puis redirigée ultérieurement par un autre service de redirection. Le service de redirection transfère l’enregistrement de redirection récupéré vers le socket TCP qu’il utilise pour proxyer le contenu d’origine à l’aide du SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL.

L’application appelant le SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS IOCTL n’a pas besoin de comprendre l’objet blob contenant l’enregistrement de redirection défini. Il s’agit d’un objet blob opaque de données que l’application doit transmettre au nouveau socket.