shorewall_code/Shorewall-docs2/MAC_Validation.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article id="MAC_Validation">
  <!--$Id$-->

  <articleinfo>
    <title>MAC Verification</title>

    <authorgroup>
      <author>
        <firstname>Tom</firstname>

        <surname>Eastep</surname>
      </author>
    </authorgroup>

    <pubdate>2005-04-06</pubdate>

    <copyright>
      <year>2001-2005</year>

      <holder>Thomas M. Eastep</holder>
    </copyright>

    <legalnotice>
      <para>Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License, Version
      1.2 or any later version published by the Free Software Foundation; with
      no Invariant Sections, with no Front-Cover, and with no Back-Cover
      Texts. A copy of the license is included in the section entitled
      <quote><ulink url="GnuCopyright.htm">GNU Free Documentation
      License</ulink></quote>.</para>
    </legalnotice>
  </articleinfo>

  <para>All traffic from an interface or from a subnet on an interface can be
  verified to originate from a defined set of MAC addresses. Furthermore, each
  MAC address may be optionally associated with one or more IP
  addresses.</para>

  <important>
    <para><emphasis role="bold">MAC addresses are only visible within an
    ethernet segment so all MAC addresses used in verification must belong to
    devices physically connected to one of the LANs to which your firewall is
    connected.</emphasis></para>
  </important>

  <important>
    <para><emphasis role="bold">Your kernel must include MAC match support
    (CONFIG_IP_NF_MATCH_MAC - module name ipt_mac.o).</emphasis></para>
  </important>

  <important>
    <para><emphasis role="bold">MAC verification is only applied to new
    incoming connection requests. </emphasis></para>
  </important>

  <section>
    <title>Components</title>

    <para>There are four components to this facility.</para>

    <orderedlist>
      <listitem>
        <para>The <emphasis role="bold">maclist</emphasis> interface option in
        <ulink
        url="Documentation.htm#Interfaces">/etc/shorewall/interfaces</ulink>.
        When this option is specified, all new connection requests arriving on
        the interface are subject to MAC verification.</para>
      </listitem>

      <listitem>
        <para>The <emphasis role="bold">maclist</emphasis> option in <ulink
        url="Documentation.htm#Hosts">/etc/shorewall/hosts</ulink>. When this
        option is specified for a subnet, all new connection requests from
        that subnet are subject to MAC verification.</para>
      </listitem>

      <listitem>
        <para>The /etc/shorewall/maclist file. This file is used to associate
        MAC addresses with interfaces and to optionally associate IP addresses
        with MAC addresses.</para>
      </listitem>

      <listitem>
        <para>The <emphasis role="bold">MACLIST_DISPOSITION</emphasis> and
        <emphasis role="bold">MACLIST_LOG_LEVEL</emphasis> variables in <ulink
        url="Documentation.htm#Conf">/etc/shorewall/shorewall.conf</ulink>.
        The MACLIST_DISPOSITION variable has the value DROP, REJECT or ACCEPT
        and determines the disposition of connection requests that fail MAC
        verification. The MACLIST_LOG_LEVEL variable gives the syslogd level
        at which connection requests that fail verification are to be logged.
        If set the the empty value (e.g., MACLIST_LOG_LEVEL="") then failing
        connection requests are not logged.</para>
      </listitem>

      <listitem>
        <para>Beginning with Shorewall 2.2.3, the <emphasis
        role="bold">MACLIST_TTL</emphasis> variable in <ulink
        url="???">/etc/shorewall/shorewall.conf</ulink>. The performance of
        configurations with a large numbers of entries in
        /etc/shorewall/maclist can be improved by setting the MACLIST_TTL
        variable.</para>

        <para>If your iptables and kernel support the "Recent Match" (see the
        output of "shorewall check" near the top), you can cache the results
        of a 'maclist' file lookup and thus reduce the overhead associated
        with MAC Verification.</para>

        <para>When a new connection arrives from a 'maclist' interface, the
        packet passes through then list of entries for that interface in
        /etc/shorewall/maclist. If there is a match then the source IP address
        is added to the 'Recent' set for that interface. Subsequent connection
        attempts from that IP address occuring within $MACLIST_TTL seconds
        will be accepted without having to scan all of the entries. After
        $MACLIST_TTL from the first accepted connection request from an IP
        address, the next connection request from that IP address will be
        checked against the entire list.</para>

        <para>If MACLIST_TTL is not specified or is specified as empty (e.g,
        MACLIST_TTL="" or is specified as zero then 'maclist' lookups will not
        be cached).</para>
      </listitem>
    </orderedlist>
  </section>

  <section>
    <title>/etc/shorewall/maclist</title>

    <para>The columns in /etc/shorewall/maclist are:</para>

    <variablelist>
      <varlistentry>
        <term>INTERFACE</term>

        <listitem>
          <para>The name of an ethernet interface on the Shorewall
          system.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>MAC</term>

        <listitem>
          <para>The MAC address of a device on the ethernet segment connected
          by INTERFACE. It is not necessary to use the Shorewall MAC format in
          this column although you may use that format if you so
          choose.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>IP Address</term>

        <listitem>
          <para>An optional comma-separated list of IP addresses for the
          device whose MAC is listed in the MAC column.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section>
    <title>Examples</title>

    <example>
      <title>Here are my files (look <ulink url="myfiles.htm">here</ulink> for
      details about my setup)</title>

      <para>/etc/shorewall/shorewall.conf:</para>

      <programlisting>MACLIST_DISPOSITION=REJECT
MACLIST_LOG_LEVEL=info</programlisting>

      <para>/etc/shorewall/interfaces:</para>

      <programlisting>#ZONE   INTERFACE       BROADCAST       OPTIONS
net     $EXT_IF         206.124.146.255 dhcp,norfc1918,routefilter,logmartians,blacklist,tcpflags,nosmurfs
loc     $INT_IF         192.168.1.255   dhcp
dmz     $DMZ_IF         -
vpn     tun+            -
Wifi    $WIFI_IF        -               maclist,dhcp
#LAST LINE - ADD YOUR ENTRIES ABOVE THIS ONE - DO NOT REMOVE</programlisting>

      <para>/etc/shorewall/maclist:</para>

      <programlisting>#INTERFACE              MAC                     IP ADDRESSES (Optional)
$WIFI_IF                00:04:5e:3f:85:b9                       #WAP11
$WIFI_IF                00:06:25:95:33:3c                       #WET11
$WIFI_IF                00:0b:4d:53:cc:97       192.168.3.8     #TIPPER
$WIFI_IF                00:1f:79:cd:fe:2e       192.168.3.6     #Work Laptop
#LAST LINE -- ADD YOUR ENTRIES ABOVE THIS LINE -- DO NOT REMOVE
</programlisting>

      <para>As shown above, I use MAC Verification on my wireless zone.</para>

      <para><note>
          <para>While marketed as a wireless bridge, the WET11 behaves like a
          wireless router with DHCP relay. When forwarding DHCP traffic, it
          uses the MAC address of the host (TIPPER) but for other forwarded
          traffic it uses it's own MAC address. Consequently, I list the IP
          addresses of both devices in /etc/shorewall/maclist.</para>
        </note></para>
    </example>

    <example>
      <title>Router in Wireless Zone</title>

      <para>Suppose now that I add a second wireless segment to my wireless
      zone and gateway that segment via a router with MAC address
      00:06:43:45:C6:15 and IP address 192.168.3.253. Hosts in the second
      segment have IP addresses in the subnet 192.168.4.0/24. I would add the
      following entry to my /etc/shorewall/maclist file:</para>

      <programlisting> $WIFI_IF                    00:06:43:45:C6:15       192.168.3.253,192.168.4.0/24</programlisting>

      <para>This entry accomodates traffic from the router itself
      (192.168.3.253) and from the second wireless segment (192.168.4.0/24).
      Remember that all traffic being sent to my firewall from the
      192.168.4.0/24 segment will be forwarded by the router so that traffic's
      MAC address will be that of the router (00:06:43:45:C6:15) and not that
      of the host sending the traffic.</para>
    </example>
  </section>
</article>