home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / sffdk10b.zip / readme.txt < prev   
Text File  |  2001-02-28  |  14KB  |  300 lines
  1.                         Firewall Development Kit
  2.                                 v1.0
  3.                             for SafeFire
  4.  
  5.                      (c) Link Guard Solutions Ltd.
  6.  
  7. 1. Introduction
  8.  
  9.       Since nobody can implement every feature particular user need, Link Guard
  10. Solutions have decided to make SafeFire configuration even more flexible by
  11. providing Firewall Development Kit. This package allows user to create it's
  12. own unique passive firewall or statistical kit that will integrate into
  13. almost any SafeFire product (the only exception is SafeFire Firewall). This
  14. package provides abilities to intercept any network packet at one or multiple
  15. points (i.e. before or after NAT module). User program can analyze packet and
  16. then choose either to pass packet futher or drop it with or without writing
  17. warning information to SafeFire log.
  18.  
  19. 2. Detailed description
  20. 2.1 Limitations
  21.  
  22.     This Kit has next functional limitations. They MAY be removed if there
  23.     will be enough requests from users.
  24.     1) It can't send any packets.
  25.     2) It can't alter any packets.
  26.     3) It does not have access to any special SafeFire functions
  27.        like Information Bus or Plugin Manager (yet normal REXX functionality
  28.        is available for REXX script, providing some additional features).
  29.     4) It can't get additional packet information, like source or
  30.        destination MAC addresses, packet priority or creation time.
  31.  
  32. 2.2 User module API
  33. 2.2.1 DLL API
  34.  
  35.     Primary interface for user module is Dynamic Link Library (DLL). It can be
  36. written in any programming language that has compiler that is able to
  37. build DLLs. All samples in this package are written in C++ programming
  38. language and must be compiled with Visual Age C++ 3.08/3.65.
  39.  
  40.     DLL may have some of next defined entry points (System calling
  41. convension). Yet any entry point can be ommited, it is recommended to have
  42. at least Write entry point or module won't be able to process packets. All
  43. entries are loaded by numbers and not names.
  44.  
  45.     There are two versions of DLL API for now - version 1.0 and version 1.1
  46. Only first (1.0) one is available in the SafeFire PPP 1.0. Main difference
  47. between them is that 1.0 DLL can't be used multiple times by single SafeFire
  48. PPP process (by loading multiple similar plugins) because it can not
  49. differenciate between instances. 1.1 version of API was introduced to resolve
  50. this problem. Single DLL can implement both APIs to work in all SafeFire PPP
  51. versions and use advanced functionality if it is available.
  52.  
  53.     List of entry point follows. Two entry point numbers is specified - one
  54. for 1.0 and other for 1.1 API. If parameter is market "v1.1 only" - it does not
  55. exists in 1.0 entry points.
  56.     1) Init entry point. Must have 200(v.1.0) or 205(v.1.1) number.
  57.        This entry point is called during plugin init.
  58.        It is passed next parameters:
  59.        - configuration file section name - ASCIIZ pointer.
  60.        - v1.1 only - instance identifier - 4 bytes pointer. Entry point should
  61.            fill memory address supplied with this parameter with unique value.
  62.            This value will be latter passed as parameter and can be used
  63.            to differenciate between instances. Caller does not use this values,
  64.            it simply pass it back when calling libarry.
  65.        It must not return anything
  66.     2) Configuration entry point. Must have 201(v.1.0) or 206(v.1.1) number.
  67.        This entry point is used to pass configuration parameters to plugin.
  68.        Every parameter that starts with "ext." will be passed to module
  69.        ("ext." prefix will be removed). Some preprocessing is done against
  70.        parameter name and value: leading and trailing blanks are removed,
  71.        value can be enclosed in double quotes (they are removed). If quoted
  72.        value has leading or trailing blanks, they are not removed.
  73.        Entry point is passed next parametes:
  74.        - v1.1 only - instance identifier - four bytes integer
  75.        - parameter name - ASCIIZ pointer
  76.        - parameter value - ASCIIZ pointer
  77.        It must not return anything
  78.     3) Write entry point. Must have 202(v.1.0) or 207(v.1.1) number.
  79.        This entry is called for each packet. This entry may be called from
  80.        multiple threads (even with same Source) and must perform serialization
  81.        by itself.
  82.        Next parameters are passed to this entry:
  83.        - v1.1 only - instance identifier - four bytes integer
  84.        - Source - four bytes integer - contains 0 if packet is going from
  85.            IN1 to IN2 and 1 if from IN2 to IN1.
  86.        - Protocol - four bytes integer - contains packet protocol number.
  87.            Please see h\sfproto.h to get full protocol list.
  88.            Note: You MUST pass any option packets (starting from 0x10000000
  89.                  protocol)
  90.        - Packet - flat pointer - pointer to packet itself.
  91.            Note: you must NOT change it's contents
  92.        - Packet Size - four bytes integer - contains packet length as received
  93.            from network (may contain padding).
  94.        - Stream Index - four bytes integer, may contain values from 0 to 0xffff
  95.            Since multiple paralel streams may be passed through the plugin
  96.            (depending on configuration), this option provides stream number.
  97.  
  98.        Returns: This entry must return 0 if it wishes to pass packet, 1 to
  99.            silently discard packet or other value (4 bytes integer) to
  100.            discard packet and log number returned to SafeFire log.
  101.  
  102.     4) Done entry point. Exists only in API v.1.1 and has 208 number.
  103.        This entry is called when plugin is to be unloaded to indicate
  104.        that resources assotiated with single parameter (instance
  105.        identifier - four bytes integer) must be freed.
  106.        It must not return anything
  107.  
  108. 2.2.2 REXX API
  109.  
  110.     Sample provided in this package was designed to perform two goals: to
  111. provide sample for anyone who wishes to write it's own module and to
  112. perform REXX transition layer. By using this sample anyone can write
  113. REXX scripts that intercept packets.
  114.     Note: REXX creates GREAT overhead if used for every packet processing,
  115.         so some prefiltering is highly recommended, especially in LAN
  116.         environment.
  117.  
  118.     REXX module must be create as single rexx script that performs multiple
  119. functions. First argument (arg(1)) value must be used to determine what
  120. function is requested. If script does not implement funciton, it MUST
  121. simply "return" without any return value.
  122.  
  123.     Next functions are defined:
  124.     1) arg(1) = 'QUERY'. This function is called first. It must be implemented
  125.         and must return decimal value that specify what other functions are
  126.         implemented with this script. Each funciton (but 'QUERY') has integer
  127.         value assotiated with. This function must return bit 'OR' of values
  128.         of all available functions.
  129.     2) arg(1) = 'LOAD', query value = 1.
  130.         This function will be called right after QUERY. It has single
  131.         additional parameter: arg(2) contains configuration section name.
  132.         This function must return anything
  133.     3) arg(1) = 'CONFIG', query value = 2.
  134.         This function is called for each configuration parameter that must
  135.         be passed. It has three additional parameters:
  136.         - arg(2) - configuration section name
  137.         - arg(3) - parameter name
  138.         - arg(4) - parameter value.
  139.         Please see DLL Configuration Entry Point above to get more
  140.         information on passing parameters to module.
  141.         This function must return anything
  142.     4) arg(1) = 'W', query value = 4.
  143.         This function is called for each packet. We'd recommend to put it to
  144.         the top of REXX file to achive maximum performance.
  145.         It is passed next parameters:
  146.         - arg(2) - configuration section name
  147.         - arg(3) - packet source - either 'IN1' or 'IN2'
  148.         - arg(4) - protocol number (binary, 4 bytes, least significant byte
  149.             first).
  150.             To check if the protocol if 0xabcd perform arg(4) = 'cdab0000'x
  151.             check.
  152.             Please see h\sfproto.h to get full protocol list.
  153.             Note: You MUST pass any option packets (starting from 10000000
  154.                   protocol)
  155.         - arg(5) - packet
  156.         - arg(6) - stream index. (binary, 4 bytes. See note about arg(4) above)
  157.             See DLL Write entry description above to get more information about
  158.             this parameter.
  159.  
  160.         This function must return decimal number. O will mean to pass packet,
  161.         1 - to drop packet, other decimal number - to drop packet and write
  162.         warning to SafeFire log.
  163.  
  164.         Note: Binary values for arg(4) and arg(6) are used to make code faster
  165.               (no integer -> string conversion, comparision of binary is faster)
  166.     5) arg(1) = 'DONE', query value = 8.
  167.         This function is called when plugin assotiated with section is to be
  168.         unloaded and rexx script can return any resources it allocated.
  169.         It is passed next parameter:
  170.         - arg(2) - configuration section name
  171.         This function must return anything
  172.         Note: This will never be called if v1.0 of API was loaded
  173.  
  174. 2.2.3 Installation and loading
  175. 2.2.3.1 DLL API
  176.  
  177.     Since DLL created using FDK (will be refered as FDK DLL below) does not
  178. implement fully functional SafeFireplugin, special SafeFire plugin (will be
  179. reffered as converter below) is use dto perform next functions:
  180.     - Provide enhanced SafeFire plugin functionality for SafeFire Plugin
  181.       Manager.
  182.     - Pass control to DLL when needed
  183.     - Hide internal API specifics (that can be changed) from DLL and perform
  184.       as "converter" from internal plugin API to FDK API.
  185.  
  186.     pl_ext.dll Plugin Library is used to hold converter plugins:
  187.     - EXTERNAL - plugin that performs as v1.0 API converter. Only this plugin
  188.                  is available in SafeFire PPP 1.0
  189.     - EXTFILT  - plugin that performs as v1.1 API converter.
  190.  
  191.     Providing information above load variable must look like the next:
  192.         load=pl_ext:external
  193.     or for v.1.1:
  194.         load=pl_ext:extfilt
  195.  
  196.     All difference between two plugins is FDK API used. All documentation below
  197. is applicable to both (you will need to supply corect "load" value in the
  198. examples.
  199.  
  200.     Converter itself uses "library" variable to know what FDK DLL to load. This
  201. variable must be specified BEFORE any "ext." variables.
  202.     Example:
  203.         library=userdll
  204.     will load "userdll.dll" as FDK DLL.
  205.  
  206.     Also converter will pass any variable with name starting with "ext." to
  207. FDK DLL.
  208.  
  209.     Converter uses two Stream Packs - IN1 and IN2. Packets from IN1 (if accepted
  210. by FDK DLL) will be sent to IN2 and vica versa. 0 will be indicated as packet
  211. source if packet was received from IN1 and 1 if from IN2.
  212.  
  213. 2.2.3.2 Examples and HOW-TO for using DLL API
  214. 2.2.3.2.1 Except from real configuration file used by one of the FDK DLL
  215.  
  216. [filter]
  217. bind=stack:extern.in1
  218.  
  219. [extern]
  220. load=pl_ext:external
  221. bind=in2:cl_pppstack.io
  222. library=sfstat
  223. ext.PipeName = sf0
  224.  
  225. 2.2.3.2.2 HOW-TO on inserting FDK DLL into existing plugin chain
  226.  
  227. If we have next configuration file ("<" and ">" characters are used to indicate
  228. variable strings that must be inserted in the corresponding places into the
  229. resulting configuration file):
  230.  
  231. ....
  232. [<someplugin>]
  233. ....
  234. bind=<somestream>:<otherplugin>.<otherstream>
  235. ....
  236.  
  237. And we want to use <userdll>.dll FDK dll between <someplugin> and <otherplugin>,
  238. the configuration file will look like the next:
  239.  
  240. ....
  241. [extern]
  242. load=pl_ext:external
  243. bind=in2:<otherplugin>.<otherstream>
  244. library=<userdll>
  245. ....put any "ext." params needed here...
  246.  
  247. [<someplugin>]
  248. ....
  249. bind=<somestream>:extern.in1
  250. ....
  251.  
  252. Note 1: If there is other "extern" section already in the file, you can use
  253.         any other unused section name, but be sure to replace extern to new
  254.         name in the last "bind" variable
  255.  
  256. Note 2: To change packet flow to reverse direction, simply replace in1 with in2
  257.         and vica versa.
  258.  
  259. Note 3: Be sure to replace pl_ext:external to pl_ext:extfilt if you want to
  260.         load v1.1 FDK DLL (or dual version DLL in 1.1 mode). You must have
  261.         at least SafeFire PPP 1.1 (is not available as of January, 2001)
  262.         to use v1.1 API.
  263.  
  264. 2.2.3.3 REXX API
  265.  
  266.     Special DLL (sample\rexxcall\ple_rexx.dll) provides C to REXX conversion
  267. layer. So it must be copied to any LIBPATH directory and installed as
  268. any other FDK DLL (See 2.2.3.1, 2.2.3.2).
  269.     This DLL supports both 1.0 and 1.1 C API version. This means that you must
  270. use
  271.     load=pl_ext:external
  272. for SafeFire PPP 1.0 and
  273.     load=pl_ext:extfilt
  274. for SafeFire PPP 1.1 or SafeFire Links.
  275.  
  276.     In the SafeFire PPP 1.0 case you can load only one instance of the DLL
  277. (but remember that you can link multiple streams to single instance).
  278.  
  279.     As soon as you installed DLL and configured your SafeFire configuration
  280. file, add ext.script variable to your plugin section ([extern] in the
  281. examples above). This variable must contain script name and must be added
  282. AFTER library variable. All the ext.* variables starting from ext.scipt
  283. will be passed to REXX script (if it supports parameter passing).
  284.  
  285.     Here is example of the [extern] section you could create:
  286. ....
  287. [extern]
  288. load=pl_ext:external
  289. library=ple_ext
  290. ext.script=c:\safefire\scripts\analyser.cmd
  291. ext.param=script parameter
  292. .....
  293.  
  294. 3 Contacts
  295.  
  296.     Last version of this kit can be found at http://www.lgs.kiev.ua
  297.     If you have any problems or questions, feel free to contact LGS support
  298.     Current support e-mail is support@lgs.kiev.ua
  299.  
  300.