Checkpoint FW-1, Version 4.0 and 4.1

Using the INSPECT language to implement stateful ICMP messages

Introduction
How does it work?
How to apply the patch?
How to use it?
Patch limitation (or features)
License
Files modified

Introduction

Checkpoint FW-1 has built-in rules to handle TCP and UDP connections in a stateful way. Unfortunately, ICMP is not covered by the built-in rules.

ICMP is mainly used in two situations:

In this example, I want to offer two new optional features:
This code is provided as an example, under a BSD style license. Feel free to modify it to reflect your needs.
Comments, flames or suggestions about this code are welcome. Please, send question not directly related to this code to the FW-1 DL.


How does it work?

For this section, it is important to understand how the prologue field defined on the User Defined Service Properties works. When you type an INSPECT command in the prologue field of an active service, this command will be executed in the prologue section, which means before the rule set is executed, and for any packet. Some good example of prologue code are provided in the $FWDIR/lib/base.def file.
  1. Stateful ping:

    2. It's implemented in two parts.
    1. Each ICMP echo-request accepted will be recorded in a new dynamic table as an existing ICMP connection.

      2. This is done by adding a case on the RECORD_CONN function defined in $FWDIR/lib. The RECORD_CONN function is called for each active rule associated with the accept action. The RECORD_CONN function provided with a default FW-1 installation deals with UDP and TCP connections and manages a dynamic table to keep track of these connections and of their states.
      We add a case matching ICMP echo-request messages, and record the source and destination IP addresses, the IP id and the ICMP sequence used in a new dynamic table.
    2. Then, in a prolog section, we accept ICMP echo-reply message if they match a recorded connection. The matching is done on the IP addresses (src = dst recorded, dst = src recorded) but also on the icmp_id and icmp_seq field. There is no limitation on the size of ICMP ping message, but when an ICMP echo-reply message match an existing entry, we delete this entry to limit replies to one ICMP echo-reply message for each ICMP echo-request message. Note that it will limit ping requests send to a local broadcast.
  2. For the ICMP stateful error messages:

    3. All is done on a prolog section.
    Each ICMP error message is checked as followed:
See the file icmpstate.def for more details. The patch will include icmpstate.def on the base.def file.

How to apply the patch?

  1. BACKUP your $FWDIR, especially the $FWDIR/lib as files will be modified.
  2. Turn OFF the dangerous Accept ICMP property.
  3. Download the file PatchICMP from http://yassp.parc.xerox.com/fw1/PatchICMP
  4. verify it's PGP signature http://yassp.parc.xerox.com/fw1/PatchICMP.asc with my PGP key
  5. check that the variable $FWDIR is setup or change directory to your $FWDIR/lib directory. (You may want to copy your $FWDIR/lib to a test directory, cd to it, and apply first the path to this test directory to verify what files are changed and how)
  6. run the patch : sh PatchICMP
    7. Note: The PatchICMP is a set of sed script, trying to do the right thing on the version (4.0 SP3, 4.1) I have tested. You may want, instead of running it, to read it and manually apply the changes, especially if you have a customize version of base.def or fwui_head.def.
  7. Reapply your ruleset. Nothing has changed yet as the patch is not turned on by default. It should compile and install ok.


How to use it?

  1. Edit $FWDIR/lib/fwui_head.def and uncomment the line which defined ICMPSTATE. It will enable to new code to run.
  2. In your ruleset, define a new service named for example pingstateful, type other
  3. in the match tab type icmp, icmp_type=ICMP_ECHO In your object file, it will looks like:
  4. in the prolog tab type ping_stateful_inbound or ping_stateful_outbound or ping_stateful_eitherbound depending on the direction you choose to apply your gateway rule on the properties setup window.
  5. Create a rule <from> your network <Destination> Any <service>pingstateful <Action> accept <Track> Long
  6. Re-apply your policy.
At this step, stateful ping is allowed from your network to any network. Up to you to refine that rule.

For enabling ICMP stateful error, add icmperror_stateful in the prolog of an active service defined as other services. For example, in a firewall where the property Apply Gateway Rules to Interface Direction matched Eitherbound, and if you have defined the pingstateful service as explained above, use the following prologue to enable stateful ping and ICMP stateful error messages :
ping_stateful_eitherbound; icmperror_stateful;. In your object file, it will looks like:


If you are running 4.1, which has the option of logging the packet accepted by the implied rules, and if this option is checked, then all ICMP packets accepted by the two prolog functions will be logged.
If you want to see really what's going on, uncomment the line defining ICMPSTATEDEBUG in $FWDIR/lib/fwui_head.def and everything will be logged.

Patch limitation (or features)

License

 
ICMP INSPECT SCRIPT
      This code is under BSD license:
 Copyright (c) 2000, Jean Chouanard , Xerox - PARC
      All rights reserved.

      Redistribution and use in source and binary forms, with or without modification, are 
      permitted provided that the following conditions are met:

           Redistributions of source code must retain the above copyright notice, this list 
           of conditions and the following disclaimer.

           Redistributions in binary form must reproduce the above copyright notice, this list 
           of conditions and the following disclaimer in the documentation and/or other
           materials provided with the distribution.

           Neither name of the Xerox-PARC nor the names of its contributors may be used to 
           endorse or promote products derived from this software without specific
           prior written permission. 

      THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY 
      EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 
      THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
      EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
      SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
      OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
      THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 


 This code is originally based of Checkpoint stateful_icmp function defined in base.def
 and from the code of William D. Burns (shadow@netscape.com), 
              http://people.netscape.com/shadow/work/inspect/index.html

 It was modify to:
      - restrict ICMP request to echo-request
      - restrict ICMP replies to echo-reply
      - check the icmp sequence (From the code of William D. Burns)
      - Delete entries from the icmp table when a match is found
        to limit ICMP reply to *one* packet (From the code of William D. Burns)
      - the recording of the outgoing accepted ICMP request in the ICMP connection table is 
        done in the CONN_RECORD macro so that only accepted request will be recorded.
      - Offer to accept ICMP error code related to existing UDP TCP or ICMP connections
        as an option

Modified files

Home

$Id: icmp.html,v 1.19 2000/07/05 02:16:46 jean Exp $; Jean Chouanard, Xerox PARC