Gestion des objets

  • Article

Cette section décrit l’utilisation correcte des types d’objets d’API de plateforme de filtrage Windows (PAM).

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 session cliente est créée en appelant FwpmEngineOpen0. La session se termine lorsque le client appelle FwpmEngineClose0 ou lorsque le processus client se termine. Lorsqu’une session est détruite, volontairement ou par l’arrêt 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 à la fin de la session.

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, FwpmTransactionCommit0 et 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 s’arrête, 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 ACID (Atomic Consistent Isolated Durable) rigoureuse.

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 la première, BFE retourne une erreur.

Si une opération échoue au cours d’une transaction, cela 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 sont ajoutés.
  • Poursuivre d’autres opérations, y compris potentiellement réessayer l’échec de FwpmFilterAdd0.

Au début 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 l’appel FwpmTransactionBegin0 ) échouent. 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, il est défini par défaut sur 15 secondes.

Chaque transaction a également un délai d’expiration de verrouillage. Il s’agit de la durée maximale pendant laquelle elle peut être propriétaire du 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. Elle est infinie 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 n’est dynamique que s’il est ajouté à l’aide d’un handle de session dynamique. Les objets dynamiques sont actifs 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 sont actifs jusqu’à ce qu’ils soient supprimés, que le BFE s’arrête ou que le système soit arrêté.
  • Persistant : 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 dans les couches 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 a terminé 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 souhaiter 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émarrage 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 démarrage automatique.

Associations d’objets

Certains objets ont des références à d’autres objets. Par exemple, un filtre référence toujours 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 le référencent n’ont pas été supprimés pour la première fois.

LUID 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 leurs GUID. Le GUID doit uniquement ê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 le 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 laisser BFE attribuer le GUID.

Tous les objets d’API PAM en mode noyau (FWPS) sont identifiés par un identificateur local unique (LUID) et référencent d’autres objets par leur LUID. Le passage de GUID à LUID permet à 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 varie d’un UINT16 à un UINT64. Les LUIDsont toujours attribués par BFE.