Objektverwaltung

In diesem Abschnitt wird die richtige Verwendung von WFP-API-Objekttypen (Windows Filtering Platform) behandelt.

Sitzungen

Die WFP-API ist sitzungsorientiert, und die meisten Funktionsaufrufe werden im Kontext einer Sitzung ausgeführt. Eine neue Clientsitzung wird durch Aufrufen von FwpmEngineOpen0erstellt. Die Sitzung endet entweder, wenn der Client FwpmEngineClose0 aufruft oder der Clientprozess beendet wird. Wenn eine Sitzung entweder zu Zweck oder durch den RPC-Rundown zerstört wird, bricht das Basisfiltermodul (Base Filtering Engine, BFE) zunächst jede vorhandene Transaktion ab.

Beim Erstellen einer neuen Sitzung kann der Aufrufer eine dynamische Sitzung erstellen, indem das FWPM_SESSION_FLAG_DYNAMIC Flag an FwpmEngineOpen0übergeben wird. Alle Während einer dynamischen Sitzung hinzugefügten Objekte werden automatisch gelöscht, wenn die Sitzung endet.

Transaktionen

Die WFP-API ist transaktional, und die meisten Funktionsaufrufe werden im Kontext einer Transaktion ausgeführt. Anrufer können FwpmTransactionBegin0, FwpmTransactionCommit0und FwpmTransactionAbort0- verwenden, um Transaktionen explizit zu steuern. Wenn jedoch ein Funktionsaufruf außerhalb einer expliziten Transaktion erfolgt, wird er innerhalb einer impliziten Transaktion ausgeführt. Wenn eine Transaktion ausgeführt wird, wenn eine Sitzung beendet wird, wird sie automatisch abgebrochen. Implizite Transaktionen werden niemals abgebrochen.

Transaktionen sind entweder schreibgeschützt oder schreibgeschützt und erzwingen strenge Atomic Consistent Isolated Durable (ACID) Semantik.

Jede Clientsitzung kann jeweils nur eine Transaktion ausgeführt haben. Wenn der Aufrufer versucht, eine zweite Transaktion zu starten, bevor ein Commit ausgeführt oder abgebrochen wird, gibt BFE einen Fehler zurück.

Wenn ein Vorgang während des Verlaufs einer Transaktion fehlschlägt, hat er keinen Einfluss auf den Gesamtstatus der Transaktion. Angenommen, der Client beginnt eine Transaktion und ruft erfolgreich FwpmFilterAdd0 dreimal auf, bevor ein vierter Aufruf fehlschlägt. Der Client hat jetzt folgende Option:

• Das Abbrechen der Transaktion, in diesem Fall werden keine Filter hinzugefügt.
• Commit für die Transaktion, in diesem Fall werden die ersten drei Filter hinzugefügt.
• Fortsetzen mit weiteren Vorgängen, einschließlich der potenziell erneuten Wiederholung des fehlgeschlagenen FwpmFilterAdd0.

Beim Beginn einer Transaktion wartet BFE, bis die txnWaitTimeoutInMSec- der Sitzung abläuft, um die Sperre zu erwerben. Wenn die Sperre innerhalb dieses Zeitraums nicht abgerufen wird, schlägt der Lock-Kauf (und der FwpmTransactionBegin0-Aufruf) fehl. Dadurch wird verhindert, dass Clients auf unbestimmte Zeit nicht reagieren. Wenn der Client kein Sperrtimeout angegeben hat, wird er standardmäßig auf 15 Sekunden festgelegt.

Jede Transaktion verfügt auch über ein Sperrtimeout. Dies ist die maximale Zeitspanne, die die Sperre besitzen kann. Wenn der Besitzer die Sperre innerhalb dieses Zeitraums nicht freigibt, wird die Transaktion versehentlich abgebrochen, wodurch die Sperre freigegeben wird. Das Sperrtimeout ist nicht konfigurierbar. Es ist unendlich für Kernelmodus-Aufrufer und eine Stunde für Benutzermodus-Aufrufer. Wenn eine Transaktion abgebrochen wird, schlägt der nächste Aufruf innerhalb dieser Transaktion mit FWP_E_TXN_ABORTEDfehl.

Objektlebensdauer

Objekte können eine von vier möglichen Lebensdauern haben:

• Dynamisch – Ein Objekt ist nur dann dynamisch, wenn es mit einem dynamischen Sitzungshandle hinzugefügt wird. Dynamische Objekte leben, bis sie gelöscht werden oder die eigene Sitzung beendet wird.
• Statisch – Objekte sind standardmäßig statisch. Statische Objekte leben, bis sie gelöscht werden, BFE stoppt oder das System heruntergefahren wird.
• Persistent – Persistente Objekte werden erstellt, indem das entsprechende FWPM_*_FLAG_PERSISTENT Flag an eine Fwpm*Add0-Funktion übergeben wird. Persistente Objekte leben bis sie gelöscht werden.
• Integrierte Objekte sind von BFE vordefiniert und können nicht hinzugefügt oder gelöscht werden. Sie leben für immer.

Filter in Kernelmodusebenen können als Startzeitfilter gekennzeichnet werden, indem das entsprechende Flag an FwpmFilterAdd0übergeben wird. Startzeitfilter werden dem System hinzugefügt, wenn der TCP/IP-Treiber gestartet wird, und entfernt, wenn BFE die Initialisierung abgeschlossen hat. Persistente Objekte werden hinzugefügt, wenn BFE gestartet wird.

In vielen Fällen möchte ein Richtlinienanbieter möglicherweise nicht, dass seine persistente Richtlinie erzwungen wird, wenn der Anbieter deaktiviert wurde. Beim Hinzufügen eines Anbieters kann der Aufrufer einen optionalen Windows-Dienstnamen angeben. Beim Hinzufügen dauerhafter Objekte kann der Aufrufer optional den Anbieter angeben, der das Objekt besitzt. Beim Start des Diensts fügt BFE dem System nur persistente Objekte hinzu, wenn sie keinem Anbieter zugeordnet sind oder der zugeordnete Anbieter keinen Windows-Dienstnamen hat oder der zugeordnete Windows-Dienst auf den automatischen Start festgelegt ist.

Objektzuordnungen

Einige Objekte weisen Verweise auf andere Objekte auf. Beispielsweise verweist ein Filter immer auf eine Ebene und kann auf eine Legende und einen Anbieterkontext verweisen. Objekte können nicht auf Objekte verweisen, die möglicherweise eine kürzere Lebensdauer aufweisen. Daher kann ein dynamisches Objekt nicht von einer anderen Sitzung auf ein dynamisches Objekt verweisen. Ein statisches Objekt kann nicht auf ein dynamisches Objekt verweisen. Ein persistentes Objekt kann nicht auf ein dynamisches Objekt, ein statisches Objekt oder ein persistentes Objekt verweisen, das einem anderen Anbieter gehört.

Ein Objekt kann erst gelöscht werden, wenn alle Objekte, die darauf verweisen, zuerst gelöscht wurden.

LUIDs und GUIDs

Alle WFP-API-Objekte im Benutzermodus (FWPM) werden durch einen global eindeutigen Bezeichner (GUID-) identifiziert und auf andere Objekte anhand ihrer GUID-s verwiesen. Die GUID- müssen nur innerhalb des Objekttyps eindeutig sein. Beispielsweise kann ein Filter und ein Anbieterkontext dieselbe GUID-aufweisen, aber zwei Filter können nicht verwendet werden. Beim Hinzufügen eines neuen Objekts können Aufrufer die GUID des Objekts zuweisen oder es null initialisiert lassen und BFE die GUID-zuweisen lassen.

Alle WFP-API-Objekte im Kernelmodus (FWPS) werden durch einen lokal eindeutigen Bezeichner (LUID) identifiziert und auf andere Objekte anhand ihrer LUID verwiesen. Der Wechsel von GUID- zu LUID- ermöglicht es WFP, nicht ausgelagerten Pool zu sparen und die Laufzeitverarbeitung zu optimieren. Die Breite der LUID- hängt vom Objekttyp ab und reicht von einem UINT16- bis zu einer UINT64-. LUIDs werden immer von BFE zugewiesen.