home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Internet Tools 1993 July / Internet Tools.iso / RockRidge / security / ipacl / README < prev    next >
Encoding:
Text File  |  1993-01-12  |  9.7 KB  |  309 lines
  1.  
  2. What is IPACL ?
  3. ---------------
  4.  
  5.     IPACL stands for `IP access list'. It has been designed
  6.     to filter incoming and outgoing TCP/UDP packets in
  7.     the SVR4/386 kernel with Lachamnn Streams TCP.
  8.     Depending on source/destination addresses and port numbers
  9.     packets can be passed through or dropped.
  10.     We run IPACL on Interactive SVR4 and on SINIX-L
  11.     (on MX300 (Intel)). I believe, that it should be easy to
  12.     port IPACL to other SVR4 bases systems, e.g. the new Solaris.
  13.  
  14. Architecture
  15. ------------
  16.  
  17.     Due to the modularity provided by AT&T's streams
  18.     concept this module could be written without
  19.     modifying any of the TCP/IP kernel sources
  20.     (You just have to install the driver and relink the kernel).
  21.     The access list module will be autopushed on /dev/ip
  22.     whenever this device is opened.
  23.     An IOCTL interface in the driver provides a facility
  24.     to download a filter program into the kernel module
  25.     (The utility command /usr/sbin/ipacl reads and compiles
  26.     a configuration file and downloads the resulting filter
  27.     program into the kernel).
  28.     All TCP and UDP packets that are sent/recived (via IP)
  29.     have to pass the access list module.
  30.     Unfortunately there is no way to filter packtes, when
  31.     your host acts as router (IPFORWARDING != 0), because
  32.     IP will not pass packets, that are to be forwarded, up
  33.     to TCP or UDP.
  34.     ICMP packetes cannot be filtered by a user supplied
  35.     filter program, but are handled in the following way:
  36.     REDIRECT packetes will be dropped and all other ICMP
  37.     packets will be passed through.
  38.     For my application, that did not worry, because I only wanted
  39.     to control access to the host, where IPACL is installed.
  40.  
  41.     +----------+----------+----------+
  42.     | TCP      | UDP      | ICMP     |         
  43.     +----------+----------+----------+
  44.     | IPACC                          |
  45.     +--------------------------------+
  46.     | IP                             |
  47.     +--------------------------------+
  48.     | Network interfaces ...         |
  49.     +----+-----+-----+---------------+
  50.      |     |     |    ...
  51.      |     |     |
  52.     LAN   SLIP   etc. ...
  53.  
  54. Source files
  55. ------------
  56.  
  57.     COPYING        GNU general public license
  58.  
  59.     Driver.c        The streams module, that sits between
  60.             /dev/tcp, /dev/udp and /dev/ip
  61.  
  62.     Makefile        The makefile
  63.  
  64.     Master        Kernel configuration files for the
  65.     System        ipacc-Driver - written according to the
  66.             SVR4 conventions
  67.  
  68.     README        The file you are currently reading
  69.  
  70.     S69ipacl        Startup script, called at boot time
  71.  
  72.     gram.doc        Brief overview of the configuration
  73.             file grammar. To get an exact definition
  74.             of the grammar look at the yacc/lex
  75.             sources in ipacl.[yl]
  76.  
  77.     ipacl.cfg        The default configuration file -
  78.             does not filter any packets
  79.  
  80.     ipacl.l        Lexical analyzer for the
  81.             configuration file - part of the
  82.             utility program /usr/sbin/ipacl
  83.  
  84.     ipacl.y        Parser for the configuration file -
  85.             part of the utility program /usr/sbin/ipacl
  86.  
  87.     matcher.c        Interpreter for the filter
  88.             program (in the kernel)
  89.  
  90.     matcher.h        Header file for matcher.c
  91.  
  92.     pkg            This directory contains all the
  93.             stuff necessary to build a SVR4 package
  94.  
  95.     sample.cfg        Sample configuration file, this file will
  96.             give you an overview how to write a
  97.             configuration file for IPACL.
  98.  
  99. Compiling and installing IPACL
  100. ------------------------------
  101.  
  102.     - First look at the Makefile, maybe you have to
  103.       change something (e.g. you want to use another C compiler).
  104.  
  105.     - Type `make' to compile the sources.
  106.  
  107.     - Type `make package' to build the SVR4 package.
  108.       The package will be built in the default package spool
  109.       directory (normally /var/spool/pkg).
  110.       (You need write access to the package spool
  111.       directory - either do it as root or do a chmod on
  112.       the directory).
  113.  
  114.     - Type `pkgadd ipacl' to install the package that has
  115.       been built in the previous step.
  116.       (Must be run as root).
  117.  
  118.     - Relink your kernel (type `/etc/conf/bin/idbuild').
  119.       (pkgadd should do this - but it is not yet implemented
  120.       in the install scripts).
  121.       (Must be run as root).
  122.  
  123.     - Edit the IPACL configuration file in /var/ipacl/ipacl.cfg.
  124.       (Must be run as root).
  125.  
  126.     - Reboot your system (type `init 6').
  127.       (Must be run as root).
  128.  
  129. Components
  130. ----------
  131.  
  132.     The installed binaries of IPACL consist of the following
  133.     components:
  134.  
  135.     - /etc/conf/...
  136.  
  137.     This is the standard place, where SVR4 drivers, master and
  138.     system files reside. The driver name of the IPACL streams
  139.     module is `ipacc'. The file names, where to find the
  140.     diriver componets in the /etc/conf subtree follow the
  141.     SVR4 conventions  (/etc/conf/pack.d/ipacc/*,
  142.     /etc/conf/sdevice.d/ipacc, ...).
  143.  
  144.     - /etc/ap/chan.ap
  145.  
  146.     This is a configuration file for the autopush command.
  147.     It is invoked the following line in /etc/inittab.
  148.  
  149.         ap::sysinit:/sbin/autopush -f /etc/ap/chan.ap
  150.  
  151.     The postinstall script of IPACL edits this file and
  152.     adds some entries to autopush `ipacc' onto /dev/ip.
  153.     E.g. postinstall adds the following lines to
  154.     /etc/ap/chan.ap (note that 24 is the major number of /dev/ip).
  155.  
  156.         # ipacc +++ do not edit this line
  157.         # push ipacc over /dev/dip
  158.         24    0    255    ipacc
  159.         # ipacc --- do not edit this line
  160.  
  161.     When the IPACL package is removed, the lines given above
  162.     will be deleted from this file.
  163.  
  164.     When you have another (e.g. vendor specific) version
  165.     of SVR4, it may be possible, that you will have to modify
  166.     something to setup autopush correctly.
  167.  
  168.     - /usr/sbin/ipacl
  169.  
  170.     This command parses the configuration file, produces
  171.     a binary filter program and loads this program down
  172.     into the ipacc driver.
  173.  
  174.     The command takes no arguments. The configuration
  175.     file has to be supplied on stdin, error messages
  176.     will be printed to stderr and on stdout there will be
  177.     printed an assembler listing of the generated filter program.
  178.  
  179.     - /var/ipacl/ipacl.cfg
  180.  
  181.     IPACL configuration file, that will be downloaded into
  182.     the kernel at boot time.
  183.  
  184.     - /etc/rc2.d/S69ipacl
  185.  
  186.     This script will be executed at system startup time and
  187.     load /var/ipacl/ipacl.cfg into the kernel.
  188.  
  189. Configuration file
  190. ------------------
  191.  
  192.     Definitions:
  193.  
  194.     Address: An address in the IPACL config file is a tuple
  195.          consisting of an internet address and a mask.
  196.          Internet addresses can be specified in dotted
  197.          notation or as host names, that will be resolved
  198.          to internet adresses with gethostbyname().
  199.          Masks can be specified in hex.
  200.          You can also use a network specification (either
  201.          in dotted notation or as network name from
  202.          /etc/networks) to specify both parts
  203.          of an IPACL address at once.
  204.  
  205.     Port:     A port in the IPACL config file is a tuple
  206.          consisting of the protocol (tcp/udp) and
  207.          a 16 bit port number.
  208.  
  209.     Sets:     IPACL allow you to define sets of addresses or
  210.          ports.
  211.  
  212.     The configuration file consists of
  213.  
  214.     - declarations and
  215.     - statements
  216.  
  217.     Declarations:
  218.  
  219.     You can use a declaration to assign a symbolic name to
  220.     an address, a port, an address set or a port set.
  221.  
  222.     Statements:
  223.  
  224.     The statements describe, how packets are to be filtered.
  225.     They are a kind of assembly notation of the filter program.
  226.  
  227.     accept                Accept the current packet
  228.                     and pass it through. No further
  229.                     statements will be executed for
  230.                     this packet.
  231.  
  232.     deny                Do not accep (drop) the current
  233.                     packet. No further statements
  234.                     will be executed for this packet.
  235.  
  236.     <cond> -> accept        If <cond> is true, then accept
  237.                     the current packet.
  238.  
  239.     <cond> -> deny            If <cond> is true, then drop
  240.                     the current packet.
  241.  
  242.     <cond> -> <label>        If <cond> is true, then
  243.                     goto <label>.
  244.  
  245.     The condition <cond> can test, wheter
  246.  
  247.         - the src/dst address of the packet matches a given
  248.           address.
  249.           The comparison is done in the following way:
  250.           (address-from-packet & address.mask) == address.address
  251.  
  252.         - the src/dst address of the packet does not match a given
  253.           address.
  254.  
  255.         - the src/dst address of the packet is (or is not) a member
  256.           of a given set of addresses.
  257.  
  258.         - the src/dst port of the packet is (or is not) a member
  259.           of a given set of ports.
  260.  
  261.         - the src/dst port of the packet is ==, !=, >, <, >=, <=
  262.           a given port.
  263.           Note, that the condition `src >= port 1024/tcp' means
  264.           protocol-in-packet == tcp && src-port-in-packet >= 1024.
  265.           Therefore `src < port 1024/tcp' is *not* the opposite
  266.           of the above condition ! This applies to the operators
  267.           <, >, <= and >=.
  268.  
  269.     The file gram.doc gives a brief description of the grammar.
  270.     A detailed description of the grammar you will find in the
  271.     lex/yacc sources ipacl.[yl] itself.
  272.     Example.cfg is a configuration file example.
  273.  
  274. Bugs
  275. ----
  276.  
  277.     - Sorry, but there exists no documentation at all.
  278.  
  279.     - The syntax for the configuration file is a little bit '&"%$'& -
  280.       it is a kind of assembler language to describe the filter
  281.       program and does not provide high level features.
  282.  
  283.     - Some parts of the program are really coded *dirty*, e.g.
  284.       fixed size arrays are used to hold some data structures and
  285.       there are no overflow checks, ...
  286.       (That's not the normal way I do programming, but IPACL
  287.       was a quick and dirty development and I never thouhgt, that
  288.       I would release ist).
  289.  
  290.     - IPACL silently drops packets, that are not allowed (and prints
  291.       a kernel message to the console). Perhaps an ICMP host unreach
  292.       message should be sent back to the sender of the packet,
  293.       but sometimes this is not desirable.
  294.  
  295.     - Forwarded packetes (IPFORWARDING != 0) cannot be filtered.
  296.  
  297. Comments, bug reports, ...
  298. --------------------------
  299.  
  300.     If you have any comments, find bugs, have some questrions, etc.,
  301.     then send mail to
  302.  
  303.     fuer@siemens.co.at
  304.  
  305.     When you make some improvements to IPACL, that might be
  306.     interresting for me or anyone else, I would be appreciated
  307.     to get a copy of the modified version too.
  308.  
  309.