Administración de objetos

En esta sección se trata el uso correcto de los tipos de objetos de API de Windows Filtering Platform (PMA).

Sesiones

La API de PMA está orientada a la sesión y la mayoría de las llamadas de función se realizan en el contexto de una sesión. Se crea una nueva sesión de cliente mediante una llamada a FwpmEngineOpen0. La sesión finaliza cuando el cliente llama a FwpmEngineClose0 o el proceso de cliente finaliza. Cuando se destruye una sesión, ya sea a propósito o por la detención rpc, el motor de filtrado base (BFE) anula primero cualquier transacción existente.

Al crear una nueva sesión, el autor de la llamada puede crear una sesión dinámica pasando la marca FWPM_SESSION_FLAG_DYNAMIC a FwpmEngineOpen0. Los objetos agregados durante una sesión dinámica se eliminan automáticamente cuando finaliza la sesión.

Transacciones

La API de PMA es transaccional y la mayoría de las llamadas de función se realizan dentro del contexto de una transacción. Los autores de llamadas pueden usar FwpmTransactionBegin0, FwpmTransactionCommit0 y FwpmTransactionAbort0 para controlar explícitamente las transacciones. Sin embargo, si una llamada de función se realiza fuera de una transacción explícita, se ejecutará dentro de una transacción implícita. Si una transacción está en curso, cuando finaliza una sesión, se anula automáticamente. Las transacciones implícitas nunca se anulan forzosamente.

Las transacciones son de solo lectura o de lectura y escritura y aplican una rigurosa semántica de durables aisladas (ACID) coherentes atómicas.

Cada sesión de cliente solo puede tener una transacción en curso a la vez. Si el autor de la llamada intenta iniciar una segunda transacción antes de confirmar o anular la primera, BFE devuelve un error.

Si se produce un error en una operación durante el transcurso de una transacción, no afecta al estado general de la transacción. Por ejemplo, supongamos que el cliente inicia una transacción y llama correctamente a FwpmFilterAdd0 tres veces antes de que se produzca un error en una cuarta llamada. El cliente ahora tiene la opción de:

• Anular la transacción, en cuyo caso no se agregará ninguno de los filtros.
• Confirmar la transacción, en cuyo caso se agregarán los tres primeros filtros.
• Continuando con más operaciones, incluida la posibilidad de volver a intentar el error FwpmFilterAdd0.

Al iniciar una transacción, BFE esperará hasta que el txnWaitTimeoutInMSec de la sesión expire para adquirir el bloqueo. Si el bloqueo no se adquiere en este momento, se producirá un error en la adquisición de bloqueos (y la llamada a FwpmTransactionBegin0 ). Esto impide que los clientes no respondan indefinidamente. Si el cliente no especificó un tiempo de espera de bloqueo, el valor predeterminado es de 15 segundos.

Cada transacción también tiene un tiempo de espera de bloqueo. Esta es la cantidad máxima de tiempo que puede poseer el bloqueo. Si el propietario no libera el bloqueo en este momento, la transacción se anula forzosamente, lo que hace que se libere el bloqueo. El tiempo de espera de bloqueo no es configurable. Es infinito para los autores de llamadas en modo kernel y una hora para los autores de llamadas en modo de usuario. Si se anula forzosamente una transacción, se producirá un error en la siguiente llamada realizada dentro de esa transacción con FWP_E_TXN_ABORTED.

Duración del objeto

Los objetos pueden tener una de las cuatro duraciones posibles:

• Dinámico: un objeto solo es dinámico si se agrega mediante un identificador de sesión dinámica. Los objetos dinámicos residen hasta que se eliminan o finaliza la sesión propietaria.
• Estático: los objetos son estáticos de forma predeterminada. Los objetos estáticos residen hasta que se eliminan, BFE se detiene o se apaga el sistema.
• Persistente: los objetos persistentes se crean pasando la marca FWPM_*_FLAG_PERSISTENT adecuada a una función Fwpm*Add0 . Los objetos persistentes residen hasta que se eliminan.
• Integrado: los objetos integrados están predefinidos por BFE y no se pueden agregar ni eliminar. Viven para siempre.

Los filtros en capas en modo kernel se pueden marcar como filtros en tiempo de arranque pasando la marca adecuada a FwpmFilterAdd0. Los filtros en tiempo de arranque se agregan al sistema cuando se inicia el controlador TCP/IP y se quitan cuando BFE finaliza la inicialización. Los objetos persistentes se agregan cuando se inicia BFE.

En muchos casos, es posible que un proveedor de directivas no desee que se aplique su directiva persistente si el proveedor se ha deshabilitado. Al agregar un proveedor, el autor de la llamada puede especificar un nombre de servicio de Windows opcional. Al agregar objetos persistentes, el autor de la llamada puede especificar opcionalmente el proveedor que "posee" ese objeto. Al iniciar el servicio, BFE solo agrega objetos persistentes al sistema si no están asociados a un proveedor, o el proveedor asociado no tiene ningún nombre de servicio de Windows o el servicio de Windows asociado se establece en inicio automático.

Asociaciones de objetos

Algunos objetos tienen referencias a otros objetos. Por ejemplo, un filtro siempre hace referencia a una capa y puede hacer referencia a una llamada y un contexto de proveedor. Los objetos no pueden hacer referencia a objetos que pueden tener una duración más corta. Por lo tanto, un objeto dinámico no puede hacer referencia a un objeto dinámico de una sesión diferente. Un objeto estático no puede hacer referencia a un objeto dinámico. Un objeto persistente no puede hacer referencia a un objeto dinámico, a un objeto estático o a un objeto persistente propiedad de un proveedor diferente.

No se puede eliminar un objeto hasta que se eliminen todos los objetos que hacen referencia a él por primera vez.

LUID y GUID

Todos los objetos de API DE PMA en modo de usuario (FWPM) se identifican mediante un identificador único global (GUID) y hacen referencia a otros objetos por sus GUID. El GUID solo debe ser único dentro del tipo de objeto. Por ejemplo, un filtro y un contexto de proveedor pueden tener el mismo GUID, pero dos filtros no. Al agregar un nuevo objeto, los llamadores pueden asignar el GUID del objeto o dejarlo inicializado con cero y dejar que BFE asigne el GUID.

Todos los objetos de API DE PMA (FWPS) del modo kernel se identifican mediante un identificador único local (LUID) y hacen referencia a otros objetos por su LUID. El cambio de GUID a LUID permite a PMA conservar el grupo no paginado y optimizar el procesamiento en tiempo de ejecución. El ancho del LUID depende del tipo de objeto y de los intervalos de un UINT16 a un UINT64. BFE siempre asigna luids.