



                            SafeFire Firewall

                               Version 1.2

              Copyright (C) 1999-2004 Link Guard Solutions Ltd.

                     EXTERNAL PLUGINS GUIDE AND REFERENCE



Contents

    1. Introduction
    2. General concepts
    3. External plugins configuration
    4. External plugins API
    5. External plugins example


1. Introduction

   Since nobody can implement every feature particular user need, Link Guard
   Solutions have decided to make SafeFire configuration even more flexible by
   providing the External Plugins feature. This feature allows user to create
   it's own unique passive firewall or statistical kit that will integrate into
   SafeFire Firewall. This feature provides abilities to intercept any network
   packet like Packet Filter and MAC Packet Filter do. User program can analyze
   packet and then choose either to pass packet further or drop it.

2. General Concepts

   The External Plugins are done as Dynamic Link Library (DLL). It can be
   written in any programming language that has compiler that is able to
   build DLLs.

   DLL may have some of next defined entry points (System calling convention).
   Any entry point except the write entry can be omitted. All entries are
   loaded by numbers and not names.

   The External Plugins feature is used within Packet Filter or MAC Packet
   Filter. To set External Plugin the special rule with action 'plugin' is
   created in these filter configurations. I.e.:

   rule=123 plugin 1

   Where 1 is the unique plugin number.

   More details about Packet Filter or MAC Packet Filter configuration are found
   in corresponding filter reference books.

   One can set as many plugins as necessary. The sequence of calling plugins is
   defined by the filter rule name. If one plugin in the such plugin chain denied
   the packet, packed will be dropped and next plugins in the chain wont be
   called.

   When the plugin is called for the packet processing, it receives full
   Ethernet frame and should parse this frame by itself. Plugin MUST NOT alter
   the frame content.

3. External plugins configuration

   The external plugins are configured independently in the [plugins] section of
   SafeFire Firewall configuration file. Please, refer to Configuration Guide And
   Reference for details about other configuration parameters.

   Each plugin are configured by one line of following syntax:

   plugin=<plugin number> <plugin dll name>

   where
      <plugin number>     - is the unique number for plugin. It is used to
                            reference plugin in the filter configuration.
      <plugin dll name>   - is the name of DLL to be used as plugin. The DLL
                            MUST have 'write' entry point (ordinal 202) and can
                            have also 'init' (200), 'config' (201) and done ('203')
                            entry points which are optional. It is advised to
                            specify here the full path to the DLL to ensure
                            SafeFire Firewall to find this DLL.

   Besides the actual plugin definition, one can set as many plugin parameters
   as necessary. All these parameters will be passed to 'config' (ordinal 201)
   entry point of plugin before any 'write' entry point calls and after 'init'
   call. Each parameter is defined by one line of following syntax:

   extvar=<plugin number>:<parameter> [<value>]

   where
      <plugin number>     - is the unique number for plugin.
      <parameter>         - parameter name
      <value>             - parameter value

   There is no additional preprocessing is done against <parameter> and <value>.
   The <parameter> must not have any whitespace characters within it.

4. External plugins API

   Each external plugin could have the following entry points (System calling
   convention):

    1) Init entry point. Must have 200 ordinal number.
       This entry point is optional and called during plugin initialization.
       It is receives following parameters:
       - plugin number - four bytes integer. This is the number of this plugin
           within SafeFire Firewall configuration.
       - instance identifier - 4 bytes pointer. Entry point should
           fill provided memory address with unique value.
           This value will be used later to identify particular instance of the plugin.
           In particular this value can be used as a pointer to plugin instance data.
       - log callback - 4 bytes pointer. Its the callback the plugin can use to
           log its messages via SafeFire Firewall logging facility.
           The format of this callback is described below this entry points list.
       It must return nothing.

    2) Initcomplete entry point. Must have 201 ordinal number.
       This entry point is optional and called after processing of SafeFire
       Firewall's configuration file to indicate that there will be no further
       calls of configuration entry point (see below).
       It is passed next parameters:
       - instance identifier - four bytes integer

       Returns: This entry point must return 0 on success of plugin
           initialization and 1 otherwise. In latter case the plugin will be
           unloaded.

    3) Configuration entry point. Must have 201 ordinal number.
       This entry point is optional and used to pass configuration parameters
       to plugin.
       Entry point is passed next parameters:
       - instance identifier - four bytes integer
       - parameter name - ASCIIZ pointer
       - parameter value - ASCIIZ pointer
       It must return nothing.

    4) Write entry point. Must have 202 ordinal number.
       This entry is required and called for each packet.
       This entry may be called from multiple threads (even with same Source)
       and must perform serialization by itself.
       Next parameters are passed to this entry:
       - instance identifier - four bytes integer
       - Source - four bytes integer - contains 0 if packet is going from the
           net to the TCP/IP stack and 1 otherwise.
       - Packet - flat pointer - pointer to full Ethernet frame.
           Note: you must NOT change it's contents
       - Packet Size - four bytes integer - contains packet length as received
           from network (may contain padding).

       Returns: This entry point must return 0 if it wishes to pass packet, 1 to
           continue processing packet within the filter, 2 to silently
           discard packet.

    5) Done entry point. Must have 203 ordinal number.
       This entry is optional and called when plugin is to be unloaded to
       indicate that resources associated with instance identifier (four bytes integer)
       must be freed.
       It must return nothing

   The log callback passed to plugin in Init entry point has System calling
   convention and receives the following parameters:

       - plugin number - four bytes integer. See Init entry point description
           for more info about this parameter.
       - log message priority - four bytes integer. See 'entries.h' for more
           info about this parameter.
       - message - ASCIIZ pointer to the message to log.

5. External plugins example

   There is a C-language header file 'entries.h' which contains definition of
   available plugin entry points.

   Also the example of external plugin written on C includes. It only logs all
   calls of plugin entry points via SafeFire Firewall logging facility with
   LOG_INFO priority.

   All these files you can find in directory API within the current documentation
   directory.


EOF

