Gestion des objets

Cette section décrit l’utilisation correcte des types d’objets API PAM (Windows Filtering Platform).

Sessions

L’API PAM est orientée session et la plupart des appels de fonction sont effectués dans le contexte d’une session. Une nouvelle session cliente est créée en appelant FwpmEngineOpen0. La session se termine lorsque le client appelle FwpmEngineClose0 ou que le processus client se termine. Lorsqu’une session est détruite, soit à des fins, soit par l’exécution RPC, le moteur de filtrage de base (BFE) abandonne d’abord toute transaction existante.

Lors de la création d’une session, l’appelant peut créer une session dynamique en passant l’indicateur FWPM_SESSION_FLAG_DYNAMIC à FwpmEngineOpen0. Tous les objets ajoutés pendant une session dynamique sont automatiquement supprimés lorsque la session se termine.

Transactions

L’API PAM est transactionnelle et la plupart des appels de fonction sont effectués dans le contexte d’une transaction. Les appelants peuvent utiliser FwpmTransactionBegin0, FwpmTransactionCommit0et FwpmTransactionAbort0 pour contrôler explicitement les transactions. Toutefois, si un appel de fonction est effectué en dehors d’une transaction explicite, il est exécuté dans une transaction implicite. Si une transaction est en cours, lorsqu’une session se termine, elle est automatiquement abandonnée. Les transactions implicites ne sont jamais abandonnées de force.

Les transactions sont en lecture seule ou en lecture/écriture et appliquent une sémantique rigoureuse de cohérence atomique isolée durable (ACID).

Chaque session cliente ne peut avoir qu’une seule transaction en cours à la fois. Si l’appelant tente de commencer une deuxième transaction avant de valider ou d’arrêter le premier, BFE retourne une erreur.

Si une opération échoue au cours d’une transaction, elle n’affecte pas l’état global de la transaction. Par exemple, supposons que le client commence une transaction et appelle correctement FwpmFilterAdd0 trois fois avant qu’un quatrième appel échoue. Le client a maintenant la possibilité de :

• Abandon de la transaction, auquel cas aucun des filtres n’est ajouté.
• Validation de la transaction, auquel cas les trois premiers filtres seront ajoutés.
• Poursuivez avec d’autres opérations, notamment la nouvelle tentative potentielle du FwpmFilterAdd0.

Lors du démarrage d’une transaction, BFE attend que le txnWaitTimeoutInMSec de la session expire pour acquérir le verrou. Si le verrou n’est pas acquis dans ce délai, l’acquisition du verrou (et la FwpmTransactionBegin0 appel) échoue. Cela empêche les clients de ne pas répondre indéfiniment. Si le client n’a pas spécifié de délai d’expiration de verrouillage, la valeur par défaut est de 15 secondes.

Chaque transaction a également un délai d’expiration de verrouillage. Il s’agit de la durée maximale pendant laquelle il peut posséder le verrou. Si le propriétaire ne libère pas le verrou dans ce délai, la transaction est abandonnée de force, ce qui entraîne la libération du verrou. Le délai d’expiration du verrouillage n’est pas configurable. Il est infini pour les appelants en mode noyau et une heure pour les appelants en mode utilisateur. Si une transaction est abandonnée de force, l’appel suivant effectué dans cette transaction échoue avec FWP_E_TXN_ABORTED.

Durées de vie des objets

Les objets peuvent avoir l’une des quatre durées de vie possibles :

• Dynamique : un objet est dynamique uniquement s’il est ajouté à l’aide d’un handle de session dynamique. Les objets dynamiques vivent jusqu’à ce qu’ils soient supprimés ou que la session propriétaire se termine.
• Statique : les objets sont statiques par défaut. Les objets statiques vivent jusqu’à ce qu’ils soient supprimés, que BFE s’arrête ou que le système soit arrêté.
• Persistent : les objets persistants sont créés en passant l’indicateur FWPM_*_FLAG_PERSISTENT approprié à une fonction Fwpm*Add0. Les objets persistants vivent jusqu’à ce qu’ils soient supprimés.
• Intégré : les objets intégrés sont prédéfinis par BFE et ne peuvent pas être ajoutés ou supprimés. Ils vivent pour toujours.

Les filtres en mode noyau peuvent être marqués comme filtres de démarrage en passant l’indicateur approprié à FwpmFilterAdd0. Les filtres de démarrage sont ajoutés au système au démarrage du pilote TCP/IP et supprimés lorsque BFE termine l’initialisation. Les objets persistants sont ajoutés au démarrage de BFE.

Dans de nombreux cas, un fournisseur de stratégie peut ne pas vouloir que sa stratégie persistante soit appliquée si le fournisseur a été désactivé. Lors de l’ajout d’un fournisseur, l’appelant peut spécifier un nom de service Windows facultatif. Lors de l’ajout d’objets persistants, l’appelant peut éventuellement spécifier le fournisseur qui « possède » cet objet. Au début du service, BFE ajoute uniquement des objets persistants au système s’ils ne sont pas associés à un fournisseur, ou si le fournisseur associé n’a pas de nom de service Windows, ou si le service Windows associé est défini sur le démarrage automatique.

Associations d’objets

Certains objets ont des références à d’autres objets. Par exemple, un filtre fait toujours référence à une couche et peut référencer une légende et un contexte de fournisseur. Les objets ne peuvent pas faire référence à des objets qui peuvent avoir une durée de vie plus courte. Par conséquent, un objet dynamique ne peut pas faire référence à un objet dynamique d’une autre session. Un objet statique ne peut pas faire référence à un objet dynamique. Un objet persistant ne peut pas faire référence à un objet dynamique, à un objet statique ou à un objet persistant appartenant à un autre fournisseur.

Un objet ne peut pas être supprimé tant que tous les objets qui font référence à celui-ci n’ont pas d’abord été supprimés.

LUIDs et GUID

Tous les objets d’API PAM en mode utilisateur (FWPM) sont identifiés par un identificateur global unique (GUID) et référencent d’autres objets par leur GUIDs. Le GUID n’a besoin que d’être unique dans le type d’objet. Par exemple, un filtre et un contexte de fournisseur peuvent avoir le même GUID, mais deux filtres ne peuvent pas. Lors de l’ajout d’un nouvel objet, les appelants peuvent affecter le GUID de l’objet ou le laisser zéro initialisé et permettre à BFE d’affecter le GUID .

Tous les objets API PAM en mode noyau (FWPS) sont identifiés par un identificateur localement unique (LUID) et référencent d’autres objets par leur LUID. Le passage de GUID à LUID permet au PAM de conserver le pool non paginé et d’optimiser le traitement au moment de l’exécution. La largeur du LUID dépend du type d’objet et des plages d’un UINT16 à un UINT64. LUID sont toujours attribués par BFE.