A rule edition plugin allows to edit Internet fitering rules with an alternative way to the Look 'n' Stop standard rule edition window. The API (Application Programming Interface) of the rule edition plugins is open. It offers to developpers and editors the ability to build new plugins.
This web page explains important principles of the Look 'n' Stop plugins API and some particularities of the rule edition plugin.

Please contact us to get a rule edition plugin VC++ 6.0 sample project.

• Rule edition plugin API
  
  The rule edition plugin API relies on the pluginAPI.h file which is common to all plugin types.

For a rule edition plugin, the functions to be exported by the plugin dll are the following:

1. PiInit - PlugIn initialisation
2. PiUninit - PlugIn uninitialisation
3. PiConfigure - PlugIn configuration through any plugin specific functions.
4. PiInfo - PlugIn information to provide to Look 'n' Stop. 
5. PiEditRulePF - PlugIn rule edition.
   

1. PiInit - PlugIn initialisation
   
   The plugin initialisation function is used by the plugin to transmit to Look 'n' Stop various data like the plugin name (ShortName), the plugin type (type) an array (of size *nb_values) of integer values (tab_values) and an array (of size *nb_values_str) of strings (tab_values_str) .
   All these plugin data will be stored by Look 'n' Stop in the registry.
   
   The PiInit function can also be used to allocate some memory for the plugin.
   
   Here is an example of PiInit function.
   

   #define PLUGIN_TYPE TYPE_PLUGIN_RULE #define NB_VALUES 5 #define NB_VALUES_STR 2 int tab_val[NB_VALUES]; char ValStr1[16]; char ValStr2[16]; char *tab_val_str[NB_VALUES_STR] = { ValStr1, ValStr2 }; char *pShortName = "My Plugin"; extern "C" __declspec( dllexport) int PiInit(  char **ShortName,  int *type,  int *nb_values,  int **tab_values,   int *nb_values_str,  char ***tab_values_str) { unsigned int i; AFX_MANAGE_STATE(AfxGetStaticModuleState()); *ShortName = pShortName; *type = PLUGIN_TYPE; *nb_values = NB_VALUES; *tab_values = tab_val; *nb_values_str = NB_VALUES_STR; *tab_values_str = tab_val_str; strcpy(ValStr1, "Test1Test1"); strcpy(ValStr1, "Test2Test2"); for(i=0;i<NB_VALUES;i++) { tab_val[i] = i*10; } return 1; }

   
   

2. PiUninit - PlugIn uninitialisation
   
   The PiUninit function is called by Look 'n' Stop when the user closes Look 'n' Stop.
   It can be used to deallocate memory previously allocated in PiInit.
    
   
3. PiConfigure - PlugIn configuration.
   
   The PiConfigure function is called by Look 'n' Stop when the user clicks on the
   Options > Advanced Options > Plugin > Configure button after having selected the plugin to configure from the Available Plugin list.
   
   The PiConfigure function is usually used to open a configuration window from which the end user will configure various options in the plugin.
   
   Here is an example of simple PiConfigure function.
   

   extern "C" __declspec( dllexport) int PiConfigure(unsigned int Info) { AFX_MANAGE_STATE(AfxGetStaticModuleState()); CConfigure config; return config.DoModal(); }

4. PiInfo - PlugIn information to provide to Look 'n' Stop. 
   
   When the users selects a plugin from the Options > Advanced Options > Plugin window, Look 'n' Stop displays information about the plugin in the right part of the window. Those information are provided by the plugin through the PiInfo function.
   
   Here is an example of simple PiInfo function.
   

   char *pShortName   = "My Rule Editor"; char *pDescription = "Customized rules."; char *pVersion     = "1.01"; char *pAuthor      = "Your name"; char *pEmail       = "[email protected]"; extern "C" __declspec( dllexport) int PiInfo(   char **ShortName,   char **Description,   char **Version,   char **Author,   char **Email,   int  *Type) { AFX_MANAGE_STATE(AfxGetStaticModuleState()); *ShortName = pShortName; *Description = pDescription; *Version = pVersion; *Author = pAuthor; *Email = pEmail; *Type = TYPE_PLUGIN_RULE; return 1; }

5. PiEditRulePF - PlugIn rule edition (the most important function).

When a user clicks on the Look 'n' Stop Add or Edit plugin extended button (>), Look 'n' Stop calls the PiEditRulePF function.  The > buttons are only shown when a Rule Edition plugin has been installed and activated.

If the user clicks the Add new rule button, the NewRule parameter is set to true and all other parameters of PiEditRulePF point to default input values.
If the user clicks the Edit rule button, the NewRule parameter is set to false and all other parameters of PiEditRulePF point to the data that define the existing rule.

The purpose of the PiEditRulePF function of the plugin is to return to Look 'n' Stop the whole definition of the rule: Name, Description, Direction, Action (allow or block) and of course, the definition of all fields and criteria that define the real filtering process (PiRule_t structure) .

The code below shows how a typical Rule Edition plugin can run its own CRuleEdition window when called by Look 'n' Stop through PiEditRulePF.

extern "C" __declspec( dllexport) int PiEditRulePF(   BOOL NewRule,   char *RuleName,   char *RuleDesc,    unsigned int *Direction,   unsigned int *AllowBlock,    PiRule_t *Rule,   void *Reserved) { AFX_MANAGE_STATE(AfxGetStaticModuleState()); CRuleEdition RuleEdition(NULL,  NewRule,  RuleName,  RuleDesc,  Direction,  AllowBlock,  Rule,  Reserved); if (RuleEdition.DoModal() == IDOK)  {  return 1;  } return 0; }

NewRule
   TRUE  if PiEditRulePF is called to add a new rule.
   FALSE if PiEditRulePF is called to edit an existing rule.

  RuleName
   Pointer to rule name string.

  RuleDesc
   Pointer to rule description string

  Direction
   Pointer to rule direction.

   Authorized values
   #define DIRECTION_UL 1    // Outbound/Uplink
   #define DIRECTION_DL 2    // Inbound/Downlink
   #define DIRECTION_ULDL 3  // Both directions

  AllowBlock
   Pointer to rule action: "allow or block".

   Authorized values
   #define ACTION_BLOCK 0
   #define ACTION_ALLOW 1

  Reserved
   Self explanatory.

  Rule
   Pointer to a PiRule_t structure that includes up to 10 fields on which the packet filtering applies.
   See below the definition of PiRule_t.

//Criteria to apply to on field. Applies to Criteria of OneField_t. #define CRITERIA_NA 0 #define CRITERIA_EQUAL_VALUE1 1 #define CRITERIA_NOTEQUAL_VALUE1 2 #define CRITERIA_RANGE_IN 3 #define CRITERIA_RANGE_OUT 4 #define CRITERIA_MASK_VALUE1 5 #define CRITERIA_NOTMASK_VALUE1 6 #define CRITERIA_RANGE_IN_REV 7 #define CRITERIA_RANGE_OUT_REV 8 #define CRITERIA_EQUAL_VALUE1OR2 9 #define CRITERIA_NOTEQUAL_VALUE1AND2 10 #define CRITERIA_EQUAL_MY_IP 100 #define CRITERIA_NOTEQUAL_MY_IP 101 //Offset type #define OFFSETTYPE_ETHERNET 0 // Apply to Ethernet Header=>position 0 #define OFFSETTYPE_IP 1       // Apply to IP Header=>position 14 #define OFFSETTYPE_TCPUDP 2   // Apply to TCP and UDP header=>position 34+4*IHL // Maximum size of a value to be compared, max = 6 for MAC Address #define MAX_SIZE_VALUE 6  typedef struct { // Offset when the rule applies to a packet that is being received unsigned int OffsetInbound;  // Offset when the rule applies to a packet that is being sent unsigned int OffsetOutbound;  // Type of Offset, ETH/IP/UDP/TCP unsigned int OffsetType;  // Size of the field to be compared unsigned int Size;  // 1st value to be used by the criteria, used for any criteria unsigned char Value1[MAX_SIZE_VALUE];  // 2nd value to be used by the criteria  // (only for RANGE and EQUALOR/NOTEQUALAND criteria) unsigned char Value2[MAX_SIZE_VALUE];  // Mask to be used for MASK criteria type unsigned char Mask [MAX_SIZE_VALUE]; // Criteria type unsigned int Criteria; } OneField_t; #define MAX_FIELD 10 // Number max of fields in a rule typedef struct { unsigned int NbFields; // Number of fields to be compared by the rule OneField_t Field[MAX_FIELD]; } PiRule_t;