<!-- Copyright (c) 2001 The FreeBSD Documentation Project

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1. Redistributions of source code (SGML DocBook) must retain the above
         copyright notice, this list of conditions and the following
         disclaimer as the first lines of this file unmodified.

      2. Redistributions in compiled form (transformed to other DTDs,
         converted to PDF, PostScript, RTF and other formats) 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.

     THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "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 NIK CLAYTON 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 DOCUMENTATION, EVEN IF ADVISED OF THE
     POSSIBILITY OF SUCH DAMAGE.
-->

<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
%articles.ent;
<!ENTITY legalnotice SYSTEM "../../share/sgml/legalnotice.sgml">
]>

<article>
  <articleinfo>
    <title>Integration of Check Point <trademark class='registered'>VPN-1</trademark>/<trademark class='registered'>Firewall-1</trademark> and FreeBSD IPsec</title>

    <authorgroup>
      <author>
	<firstname>Jon</firstname>
	<surname>Orbeton</surname>

	<affiliation>
	  <address><email>jono@securityreports.com</email></address>
	</affiliation>
      </author>

      <author>
	<firstname>Matt</firstname>
	<surname>Hite</surname>

	<affiliation>
	  <address><email>mhite@hotmail.com</email></address>
	</affiliation>
      </author>
    </authorgroup>

    <pubdate>$FreeBSD$</pubdate>

    <copyright>
      <year>2001</year>
      <year>2002</year>
      <year>2003</year>
      <holder role="mailto:jono@securityreports.com">Jon Orbeton</holder>
    </copyright>

    &legalnotice;

    <legalnotice id="trademarks" role="trademarks">
      &tm-attrib.freebsd;
      &tm-attrib.check-point;
      &tm-attrib.general;
    </legalnotice>

    <abstract>
      <para>This document explains how to configure a <acronym>VPN</acronym>
	tunnel between FreeBSD and Check Point's
	<trademark class='registered'>VPN-1</trademark>/
	<trademark class='registered'>Firewall-1</trademark>.  Other
	documents provide similar information, but do not contain instructions
	specific to VPN-1/Firewall-1 and its integration with FreeBSD.  These
	documents are listed at the conclusion of this paper for further
	reference.</para>
    </abstract>
  </articleinfo>

  <sect1 id="prerequisites">
    <title>Prerequisites</title>

    <para>The following is a diagram of the machines and networks referenced
      in this document.</para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="networks">
      </imageobject>

      <textobject>
        <literallayout class="monospaced">External Interface                    External Interface
           208.229.100.6                    216.218.197.2
                       |                    |
         +--&gt; Firewall-1 &lt;--&gt; Internet &lt;--&gt; FreeBSD GW &lt;--+
         |                                                |
FW-1 Protected Nets                              Internal Nets
199.208.192.0/24                               192.168.10.0/24</literallayout>
      </textobject>

      <textobject>
        <phrase>FW-1 net and FreeBSD net</phrase>
      </textobject>
    </mediaobject>

    <para>The FreeBSD gateway <acronym>GW</acronym> serves as a firewall and
      <acronym>NAT</acronym> device for <quote>internal nets.</quote></para>

    <para>The FreeBSD kernel must be compiled to support IPsec.  Use the
      following kernel options to enable IPsec support in your kernel:</para>

<programlisting>options         IPSEC
options         IPSEC_ESP
options         IPSEC_DEBUG</programlisting>

    <para>For instructions on building a custom kernel, refer to the
      <ulink url="&url.books.handbook;/kernelconfig.html">FreeBSD
	handbook</ulink>. Please note that <acronym>IP</acronym>
      protocol&nbsp;50 (<acronym>ESP</acronym>) and <acronym>UDP</acronym>
      port&nbsp;<literal>500</literal> must be open between the <trademark class='registered'>Firewall-1</trademark>
      host and the FreeBSD <acronym>GW</acronym>.</para>

    <para>Also, <application>racoon</application> must be installed to support
      key exchange.  <application>Racoon</application> is part of the FreeBSD
      ports collection in <filename role="package">security/racoon</filename>.
      The <application>racoon</application> configuration file will be covered
      later in this document.</para>
  </sect1>

  <sect1 id="object">
      <title>Firewall-1 Network Object Configuration</title>

    <para>Begin by configuring the Firewall-1 Policy.  Open the Policy Editor
      on the Firewall-1 Management server and create a new
      <quote>Workstation</quote> Network Object representing FreeBSD
      <acronym>GW</acronym>.</para>

<programlisting>General Tab:
		Set name and IP address

VPN Tab:
		Encryption Schemes Defined:             IKE               ---&gt; Edit

IKE Properties:
		Key Negotiation Encryption Methods:     3DES

Authentication Method:
		Pre-Shared Secret ---&gt; Edit</programlisting>

    <para>Select the Firewall Object and set a pre-shared secret.
      (Do not use our example.)</para>

<programlisting>Support Aggressive Mode:                 Checked
Supports Subnets:                      Checked</programlisting>

    <para>After setting the pre-shared secret in the Firewall-1 Network Object
      definition, place this secret in the
      <filename>/usr/local/etc/racoon/psk.txt</filename> file on FreeBSD
      <acronym>GW</acronym>.  The format for <filename>psk.txt</filename>
      is:</para>

<programlisting>208.229.100.6          rUac0wtoo?</programlisting>

  </sect1>

  <sect1 id="rulecfg">
    <title>Firewall-1 VPN Rule Configuration</title>

    <para>Next, create a Firewall-1 rule enabling encryption between the
      FreeBSD <acronym>GW</acronym> and the Firewall-1 protected network.
      In this rule, the network services permitted through the
      <acronym>VPN</acronym> must be defined.</para>

<programlisting>Source            | Destination        | Service      | Action  | Track
------------------------------------------------------------------------
FreeBSD GW        | FW-1 Protected Net | VPN services | Encrypt | Long
FW-1 Protected Net| FreeBSD GW         |              |         |</programlisting>

    <para><quote>VPN services</quote> are any services (i.e.
      <command>telnet</command>, <acronym>SSH</acronym>,
      <acronym>NTP</acronym>, etc.) which remote hosts are permitted to access
      through the <acronym>VPN</acronym>.  Use caution when permitting
      services; hosts connecting through a <acronym>VPN</acronym> still
      represent a potential security risk.  Encrypting the traffic between the
      two networks offers little protection if a host on either side of the
      tunnel has been compromised.</para>

    <para>Once the rule specifying data encryption between the FreeBSD
      <acronym>GW</acronym> and the Firewall-1 protected network has been
      configured, review the <quote>Action Encrypt</quote> settings.</para>

<programlisting>Encryption Schemes Defined:     IKE ---&gt; Edit
Transform:                      Encryption + Data Integrity (ESP)
Encryption Algorithm:           3DES
Data Integrity:                 MD5
Allowed Peer Gateway:           Any or Firewall Object
Use Perfect Forward Secrecy:    Checked</programlisting>

    <para>The use of Perfect Forward Secrecy (<acronym>PFS</acronym>) is
      optional.  Enabling <acronym>PFS</acronym> will add another layer of
      encryption security, but does come at the cost of increased
      <acronym>CPU</acronym> overhead.  If <acronym>PFS</acronym> is not used,
      uncheck the box above and comment out the
      <literal>pfs_group&nbsp;1</literal> line in the
      <filename>racoon.conf</filename> file on FreeBSD <acronym>GW</acronym>.
      An example <filename>racoon.conf</filename> file is provided later in
      this document.</para>

  </sect1>

  <sect1 id="policy">
    <title>FreeBSD <acronym>VPN</acronym> Policy Configuration</title>

    <para>At this point, the <acronym>VPN</acronym> policy on FreeBSD
      <acronym>GW</acronym> must be defined.  The &man.setkey.8; tool performs
      this function.</para>

    <para>Below is an example shell script which will flush &man.setkey.8; and
      add your <acronym>VPN</acronym> policy rules.</para>

<programlisting>#
# /etc/vpn1-ipsec.sh
#
# IP addresses
#
#     External Interface                    External Interface
#       208.229.100.6                       216.218.197.2
#                   |                       |
#        +--&gt; Firewall-1 &lt;--&gt; Internet &lt;--&gt; FreeBSD GW &lt;--+
#        |                                                |
# FW-1 Protected Nets                              Internal Nets
#    199.208.192.0/24                                  192.168.10.0/24
#
# Flush the policy
#
setkey -FP
setkey -F
#
# Configure the Policy
#
setkey -c &lt;&lt; END
spdadd 216.218.197.2/32 199.208.192.0/24 any -P out ipsec
esp/tunnel/216.218.197.2-208.229.100.6/require;
spdadd 199.208.192.0/24 216.218.197.2/32 any -P in ipsec
esp/tunnel/208.229.100.6-216.218.197.2/require;
END
#</programlisting>

    <para>Execute the &man.setkey.8; commands:</para>

    <screen>&prompt.root; <userinput>sh /etc/vpn1-ipsec.sh</userinput></screen>
  </sect1>

  <sect1 id="racoon">
    <title>FreeBSD <application>Racoon</application> Configuration</title>

    <para>To facilitate the negotiation of IPsec keys on the FreeBSD
      <acronym>GW</acronym>, the
      <filename role="package">security/racoon</filename> port must be
      installed and configured.</para>

    <para>The following is a <application>racoon</application> configuration
      file suitable for use with the examples outlined in this document.
      Please make sure you fully understand this file before using it in a
      production environment.</para>

<programlisting># racoon.conf for use with Check Point VPN-1/Firewall-1
#
# search this file for pre_shared_key with various ID key.
#
        path pre_shared_key "/usr/local/etc/racoon/psk.txt" ;
        log debug;
#
# "padding" defines some parameter of padding.  You should not touch these.
#
        padding
      {
        maximum_length 20;      # maximum padding length.
        randomize off;          # enable randomize length.
        strict_check off;       # enable strict check.
        exclusive_tail off;     # extract last one octet.
      }

        listen
      {
        #isakmp ::1 [7000];
        #isakmp 0.0.0.0 [500];
        #admin [7002];          # administrative port by kmpstat.
        #strict_address;        # required all addresses must be bound.
      }
#
# Specification of default various timers.
#
        timer
      {
#
# These values can be changed per remote node.
#
        counter 5;              # maximum trying count to send.
        interval 20 sec;        # maximum interval to resend.
        persend 1;              # the number of packets per a send.
#
# timer for waiting to complete each phase.
#
        phase1 30 sec;
        phase2 15 sec;
      }

        remote anonymous
      {
        exchange_mode aggressive,main; # For Firewall-1 Aggressive mode

        #my_identifier address;
        #my_identifier user_fqdn "";
        #my_identifier address "";
        #peers_identifier address "";
        #certificate_type x509 "" "";

        nonce_size 16;
        lifetime time 10 min;   # sec,min,hour
        lifetime byte 5 MB;     # B,KB,GB
        initial_contact on;
        support_mip6 on;
        proposal_check obey;    # obey, strict or claim

        proposal {
                encryption_algorithm 3des;
                hash_algorithm md5;
                authentication_method pre_shared_key;
                dh_group 2 ;
        }
      }

        sainfo anonymous
      {
        pfs_group 1;
        lifetime time 10 min;
        lifetime byte 50000 KB;
        encryption_algorithm 3des;
        authentication_algorithm hmac_md5;
        compression_algorithm deflate ;
      }</programlisting>

    <para>Ensure that the <filename>/usr/local/etc/racoon/psk.txt</filename>
      file contains the pre-shared secret configured in the <quote>Firewall-1
      Network Object Configuration</quote> section of this document and has
      mode <literal>600</literal> permissions.</para>

    <screen>&prompt.root; <userinput>chmod 600 /usr/local/etc/racoon/psk.txt</userinput></screen>

  </sect1>

  <sect1 id="startingvpn">
    <title>Starting the <acronym>VPN</acronym></title>

    <para>You are now ready to launch <application>racoon</application> and
      test the <acronym>VPN</acronym> tunnel.  For debugging purposes, open
      the Firewall-1 Log Viewer and define a log filter to isolate entries
      pertaining to FreeBSD <acronym>GW</acronym>.  You may also find it
      helpful to &man.tail.1; the <application>racoon</application>
      log:</para>

    <screen>&prompt.root; <userinput>tail -f /var/log/racoon.log</userinput></screen>

    <para>Start <application>racoon</application> using the following
      command:</para>

    <screen>&prompt.root; <userinput>/usr/local/sbin/racoon -f /usr/local/etc/racoon/racoon.conf</userinput></screen>

    <para>Once <application>racoon</application> has been launched,
      &man.telnet.1; to a host on the Firewall-1 protected network.</para>

    <screen>&prompt.root; <userinput>telnet -s 192.168.10.3 199.208.192.66 22</userinput></screen>

    <para>This command attempts to connect to the &man.ssh.1; port on <hostid
      role="ipaddr">199.208.192.66</hostid>, a machine in the Firewall-1
      protected network.  The <option>-s</option> switch indicates the source
      interface of the outbound connection.  This is particularly important
      when running <acronym>NAT</acronym> and <acronym>IPFW</acronym> on
      FreeBSD <acronym>GW</acronym>.  Using <literal>-s</literal> and
      specifying an explicit source address prevents <acronym>NAT</acronym>
      from mangling the packet prior to tunneling.</para>

    <para>A successful <application>racoon</application> key exchange will
      output the following to the <filename>racoon.log</filename> log
      file:</para>

<programlisting>pfkey UPDATE succeeded: ESP/Tunnel 216.218.197.2->208.229.100.6
pk_recvupdate(): IPSec-SA established: ESP/Tunnel 216.218.197.2->208.229.100.6
get pfkey ADD message IPsec-SA established: ESP/Tunnel 208.229.100.6->216.218.197.2</programlisting>

    <para>Once key exchange completes (which takes a few seconds), an
      &man.ssh.1; banner will appear.  If all went well, two <quote>Key
      Install</quote> messages will be logged in the Firewall-1 Log
      Viewer.</para>

<programlisting>Action      |  Source        |  Dest.             | Info.
Key Install |  216.218.197.2 |  208.229.100.6     | IKE Log: Phase 1 (aggressive) completion.
Key Install |  216.218.197.2 |  208.229.100.6     | scheme: IKE methods</programlisting>

    <para>Under the information column, the full log detail will read:</para>

<programlisting>IKE Log: Phase 1 (aggressive) completion. 3DES/MD5/Pre shared secrets Negotiation Id:
scheme: IKE methods: Combined ESP: 3DES + MD5 + PFS (phase 2 completion) for host:</programlisting>
  </sect1>

  <sect1 id="References">
    <title>References</title>

    <itemizedlist>
      <listitem>
	<para>The FreeBSD Handbook: VPN over IPsec.
        <ulink url="&url.books.handbook;/ipsec.html"></ulink></para>
      </listitem>

      <listitem>
        <para>KAME Project.
	<ulink url="http://www.kame.net"></ulink></para>
      </listitem>

      <listitem>
        <para>FreeBSD IPsec mini-HOWTO.
	<ulink url="http://www.x-itec.de/projects/tuts/ipsec-howto.txt"></ulink></para>
      </listitem>
    </itemizedlist>
  </sect1>
</article>
